---
title: "Instalação da estação de trabalho"
description: "Como instalar os componentes da estação de trabalho do TrustBridge, Workstation Service e Tray App, com um MSI e uma linha de msiexec, além dos modelos de Diretiva de Grupo."
canonical: "https://docs.lacunasoftware.com/articles/trustbridge/workstation-installation"
locale: "pt-BR"
product: "TrustBridge"
last_updated: "2026-10-12"
---

# Instalação da estação de trabalho

**Um MSI, uma linha de `msiexec`, e uma máquina limpa passa a aguardar na fila de admissão.** O
pacote `TrustBridge-Workstation-<version>-x64.msi` traz os dois componentes da estação de trabalho, o
Workstation Service e o Tray App, publicados como autocontidos (self-contained), então uma máquina sem
runtime do .NET não precisa de nada instalado antes. Junto com ele, a Lacuna Software fornece
`TrustBridge-Workstation-GroupPolicy-<version>.zip`, com os modelos de Diretiva de Grupo.

Esta página é o que o operador **digita**. A página
[Configuração da estação de trabalho](https://docs.lacunasoftware.com/articles/trustbridge/workstation-configuration) é o que cada valor pode **dizer**:
cada configuração que o serviço aceita, o padrão dela e o que um valor inválido provoca.

## Antes de começar

- **Uma máquina Windows de 64 bits e direitos administrativos nela.** O pacote é por máquina, somente
  x64, e exige o Windows Installer 5.0 (Windows 7 e posteriores). ARM64 não é suportado.
- **Nada mais instalado.** Os dois componentes são autocontidos, e é por isso que o pacote tem cerca
  de 100 MB.
- **A URL do Servidor, acessível a partir da máquina.** O único valor sem o qual a instalação se
  recusa a prosseguir.
- **A licença do PKI SDK**, o conteúdo inteiro de um `LacunaPkiLicense.config` codificado em base64
  em uma linha. O instalador não a exige, e uma máquina sem ela não valida nada e não assina nada.
- **Um Administrador que vá admitir a máquina.** Instalar não faz a máquina entrar na frota; uma
  pessoa faz isso, no Servidor.
- **Uma cadeia TLS em que a máquina confie.** O Workstation Service recusa um certificado de Servidor
  não confiável, e o sintoma é uma máquina que nunca aparece na fila.

## A linha única

```powershell
msiexec /i TrustBridge-Workstation-1.0.1-x64.msi /qn SERVER_URL=https://trustbridge.example.com PKI_LICENSE=<base64>
```

Essa é uma instalação completa para a frota. Em ordem, ela:

1. Verifica `SERVER_URL` e faz a transação inteira falhar se o valor estiver vazio ou não começar com
   um esquema.
2. Coloca os dois componentes em `C:\Program Files\TrustBridge\`, cria a árvore de estado da máquina
   em `C:\ProgramData\TrustBridge\`, com uma DACL que só admite Administradores e LocalSystem, e
   registra a entrada de inicialização automática do Tray App.
3. Grava a configuração da instalação em `HKLM\Software\TrustBridge`.
4. Registra o **TrustBridge Workstation Service** no SCM (LocalSystem, inicialização automática,
   reinício em caso de falha) e o inicia, aguardando a inicialização ser bem-sucedida.
5. O serviço gera a **Chave da Estação de Trabalho** no TPM da máquina (recorrendo ao provider de
   software, se necessário), se anuncia ao Servidor e fica **Pendente** na fila de admissão.

**O último ato da instalação é o serviço subir.** Um serviço que se recusa a iniciar (uma licença que
o SDK não lê, uma `INSTALLER_KEY` que não é uma chave) faz a instalação falhar e ser revertida, em vez
de deixar uma máquina que parece instalada e nunca se conecta.

**O `msiexec` não espera.** Ele retorna imediatamente, e a linha seguinte de um script de implantação
é executada enquanto a instalação ainda está em andamento. Para ler o resultado, aguarde o processo:

```powershell
$install = Start-Process msiexec -Wait -PassThru -ArgumentList @(
    '/i', 'TrustBridge-Workstation-1.0.1-x64.msi',
    '/qn',
    '/l*v', 'C:\Windows\Temp\trustbridge-install.log',
    'SERVER_URL=https://trustbridge.example.com',
    'PKI_LICENSE=PD94bWwgdmVyc2lvbj0…'
)
$install.ExitCode
```

Os códigos de saída são os do próprio Windows Installer: **0** sucesso, **1602** cancelado, **3010**
sucesso com algo pedindo reinicialização, **1603** erro fatal, que é como as duas recusas próprias
deste pacote aparecem. O motivo é uma linha do log `/l*v`; procure nele por `SERVER_URL` ou
`newer version`.

### As três propriedades

As três são gravadas em `HKLM\Software\TrustBridge` como valores de Registro, e não em um arquivo de
configuração, e é isso que as faz sobreviver a uma atualização sem nenhum mecanismo para lembrar
propriedades.

| Propriedade | Valor no Registro | Chave de configuração | |
|---|---|---|---|
| `SERVER_URL` | `ServerUrl` | `Server:Url` | **Obrigatória**, a menos que o build traga um padrão embutido. Controlada pela condição de inicialização. |
| `PKI_LICENSE` | `PkiLicense` | `Certificates:Validation:License` | Opcional para o instalador; uma máquina sem ela não assina nada. |
| `INSTALLER_KEY` | `InstallerKey` | `Server:InstallerKey` | Opcional. A maioria das implantações nunca a passa. |

`PKI_LICENSE` só é opcional no sentido de que o MSI não a verifica. Sem licença, todo certificado da
máquina aparece como `UNTRUSTED`, e o serviço avisa isso uma vez na inicialização. Passe-a, ou
publique-a por Diretiva de Grupo antes que se espere que a máquina funcione.

`INSTALLER_KEY` é para uma implantação que gerou uma Installer Key própria e configurou a metade
pública dela no Servidor, em `Admission:InstallerKeys`. Se não for definida, nenhum valor é gravado e
vale a chave do próprio produto. Ela não é um segredo e não admite nada sozinha.

Nenhuma das três deve precisar de aspas. Uma URL não tem espaços, e a licença e a chave são base64 em
uma linha.

### A condição de inicialização

**`SERVER_URL` precisa estar presente e começar com `http://` ou `https://`**, ou a transação falha
antes que qualquer coisa seja gravada. Vale para instalações silenciosas e interativas; para
instalação, atualização e reparo, embora uma atualização e um reparo a satisfaçam com o valor que a
própria máquina já tem, sem que você precise passar nada. A única transação que ela não controla é a
remoção. Um serviço que se recusasse a iniciar seria uma máquina em loop de falhas, descoberta quando
alguém não conseguisse assinar; uma instalação recusada é uma falha única e visível enquanto alguém
está acompanhando.

Um build pode trazer uma URL de Servidor padrão embutida; assim, a linha para a frota passa a ser
`msiexec /i <msi> /qn` e o campo interativo já vem preenchido. Um valor na linha de comando continua
prevalecendo, assim como o valor que a máquina já tem.

### O que uma instalação coloca na máquina

| | |
|---|---|
| `C:\Program Files\TrustBridge\Workstation Service\` | O serviço e o runtime autocontido dele |
| `C:\Program Files\TrustBridge\Tray App\` | O Tray App e o runtime próprio dele |
| `C:\ProgramData\TrustBridge\` | O estado da máquina: o Cache de PIN, o chaveiro dele, o conjunto de Autoridades Certificadoras Confiáveis em cache. Somente Administradores e LocalSystem |
| `C:\ProgramData\TrustBridge\anchors\` | Onde ficam os arquivos de âncora de confiança, com a mesma DACL |
| `HKLM\Software\TrustBridge` | Os três valores definidos na instalação |
| `HKLM\…\CurrentVersion\Run` → `TrustBridge Tray App` | Inicialização automática para toda a máquina, para que o Tray seja executado para todo usuário interativo |
| Serviço `TrustBridge Workstation Service` | LocalSystem, automático, reinicia três vezes em caso de falha, em intervalos de um minuto |
| Origem de eventos de Aplicativo `TrustBridge Workstation Service` | Onde são gravados uma recusa ocorrida antes de o log existir e o relatório de limpeza de uma desinstalação |

O diretório de instalação é fixo. A **Chave da Estação de Trabalho** não está nesta tabela porque o
serviço a gera em um container CNG na primeira vez que inicia, e nada além do próprio verbo de limpeza
do serviço consegue removê-la.

**O Tray App só aparece no próximo login.** Em uma máquina em que alguém já está conectado, o ícone
aparece depois que a pessoa sai e entra de novo, ou quando `Tray App\TrustBridge.TrayApp.exe` é
iniciado manualmente. Enquanto ele não estiver em execução, não há ninguém para responder a uma
solicitação de PIN.

## Instalando interativamente

Clicar duas vezes no MSI mostra uma tela própria deste pacote entre as telas padrão de progresso e de
conclusão: em uma máquina limpa, um único campo **Server URL**, associado à mesma propriedade
`SERVER_URL`; em uma máquina que já tem o pacote, uma tela para **reparar, reapontar ou remover**, com
o campo já preenchido. Não há EULA, seletor de diretório nem árvore de recursos. **As caixas de
diálogo são somente em inglês**, de propósito: são ferramentas de implantação para o operador. O Tray
App que o usuário vê fala o idioma do usuário.

A licença e a Installer Key não têm campo. Forneça-as a uma máquina interativa isolada por uma linha
de reparo silencioso ou por Diretiva de Grupo.

## Admitindo a máquina

**Instalar não faz a máquina entrar na frota.** A máquina se anuncia e aguarda, **Pendente**, até que
um Administrador a torne **Admitida** na fila de admissão, em `/admin/admission`. Até lá, o serviço
está em execução, acessando o Servidor e sem se conectar a nada; o log dele diz o motivo a cada
reconexão, e o Tray App mostra *Ainda não admitida*.

O que admitir significa é limitado, e a tela diz isso: sem um canal externo (out-of-band) com que
conferir uma impressão digital, admitir é uma barreira humana, com limite de requisições, sobre uma
fila. Uma máquina é *notada*, e não *verificada*. O que torna isso aceitável é que a etapa não é
opcional; nada que a máquina tenha a admite sozinha. Leia o nome do host, o sistema operacional, as
versões e a **postura da chave** (em hardware ou em software) da máquina antes de admiti-la.

Depois de admitida, a máquina se conecta na próxima tentativa de reconexão e aparece na tela
**Estações de Trabalho**, em `/admin/fleet`. Uma máquina devolvida a Pendente mantém a chave e o
histórico; uma máquina **Revogada** é recusada permanentemente e não tem como voltar, exceto como uma
máquina nova, com uma chave nova.

Uma requisição Pendente abandonada expira depois de `Admission:PendingExpiry` (7 dias por padrão,
contados a partir da **última** requisição da máquina), e a linha dela é excluída. Isso não é uma
recusa; a máquina simplesmente pede de novo, como uma que a plataforma nunca viu.

### Se a máquina nunca aparece na fila

Leia primeiro o que o próprio serviço registra: o log Aplicativo do Windows, origem **TrustBridge
Workstation Service**, e o log do serviço. Quatro coisas fazem uma requisição de admissão ser
recusada, e o Servidor deliberadamente não diz qual, então o log da máquina cita as quatro: a máquina
foi revogada; a Installer Key dela não é uma em que este Servidor confia; vieram requisições demais do
endereço dela; ou a fila está cheia. As duas últimas se resolvem sozinhas.

**O serviço informa de onde veio cada um dos três valores definidos na instalação, a cada
inicialização**, uma linha por valor, no formato *`Server:Url` is https://…, supplied by …*. Leia isso
antes de mexer no Registro.

```powershell
sc.exe query "TrustBridge Workstation Service"
Get-ItemProperty 'HKLM:\Software\TrustBridge'
Get-ItemProperty 'HKLM:\Software\Policies\TrustBridge' -ErrorAction SilentlyContinue
```

**Execute esses comandos em um PowerShell de 64 bits.** A preferência fica na visão de 64 bits do
Registro; um host de 32 bits é redirecionado para `WOW6432Node`, onde uma máquina perfeitamente
configurada parece vazia.

São dois locais, porque o segundo prevalece: um valor de Diretiva de Grupo em
`HKLM\Software\Policies\TrustBridge` vence o que o instalador gravou, e uma máquina apontando para o
Servidor errado normalmente é uma máquina no escopo de uma GPO de que alguém se esqueceu. Os dois são
lidos **uma vez, na inicialização**.

## Diretiva de Grupo: implantando os modelos

O modelo ADMX permite que um domínio defina dois valores em toda a frota: `Server:Url` e
`Certificates:Validation:License`. Ele nunca é instalado pelo MSI: nada que o pacote grava pode ficar
em `\Policies`, porque o processamento de diretivas exclui os valores que deixa de gerenciar.
Descompactado, o arquivo de modelos da versão tem três arquivos:

```text
admx\TrustBridge.admx
admx\en-US\TrustBridge.adml
admx\pt-BR\TrustBridge.adml
```

Copie-os para o repositório central do domínio, incluindo as pastas de idioma:

```powershell
$store = "\\$env:USERDNSDOMAIN\SYSVOL\$env:USERDNSDOMAIN\Policies\PolicyDefinitions"
New-Item -ItemType Directory -Force -Path $store, "$store\en-US", "$store\pt-BR" | Out-Null
Copy-Item admx\TrustBridge.admx $store
Copy-Item admx\en-US\TrustBridge.adml "$store\en-US"
Copy-Item admx\pt-BR\TrustBridge.adml "$store\pt-BR"
```

A linha `New-Item` não é mera formalidade: `Copy-Item` para uma pasta que não existe cria um
*arquivo* com esse nome, e um repositório nesse estado fica quebrado de um jeito de que nada reclama.
Uma máquina sem repositório central recebe os mesmos três arquivos em
`%SystemRoot%\PolicyDefinitions`. De qualquer forma, as configurações aparecem em **Configuração do
Computador → Modelos Administrativos → TrustBridge Workstation**.

**Copie os dois idiomas, mesmo que os seus administradores leiam inglês.** O `gpedit` recorre ao
idioma alternativo por arquivo, e não por string, então um repositório sem
`pt-BR\TrustBridge.adml` faz um console em português perder o modelo inteiro.

**Uma alteração de diretiva exige reiniciar o serviço, não atualizar a Diretiva de Grupo.** O serviço
lê os dois locais do Registro uma vez, na inicialização. O `gpupdate /force` entrega o valor, e a
máquina o adota na próxima inicialização do serviço:

```powershell
Restart-Service "TrustBridge Workstation Service"
```

**Renovar a licença é a razão de ser da segunda diretiva.** Sem uma licença válida, todo certificado
de toda máquina aparece como `UNTRUSTED`, então um vencimento seria, de outra forma, uma
indisponibilidade em toda a frota, resolvida executando o MSI de novo em todas as máquinas. Publicada
como diretiva, é uma atualização e uma onda de reinícios.

Não há, de propósito, diretiva para a Installer Key: uma troca de chave é uma implantação em etapas
(informe a chave nova ao lado da antiga no Servidor, atualize as máquinas, remova a entrada antiga), e
não uma atualização de GPO.

## Reparando e reapontando

Um reparo reinstala o pacote e regrava os três valores de Registro a partir das propriedades, e é
assim que você altera a configuração de instalação de uma máquina sem desinstalá-la:

```powershell
# Repair: put back what a machine lost, keeping its current configuration.
msiexec /i TrustBridge-Workstation-1.0.1-x64.msi /qn REINSTALL=ALL REINSTALLMODE=ecmus

# Re-point: the same transaction, with a new value.
msiexec /i TrustBridge-Workstation-1.0.1-x64.msi /qn REINSTALL=ALL REINSTALLMODE=ecmus `
    SERVER_URL=https://trustbridge-2.example.com
```

Uma propriedade que você não passa é lida de novo da máquina e regravada sem alteração. O serviço é
parado e iniciado pela transação, então um reapontamento entra em vigor quando o reparo termina. A
máquina mantém a Chave da Estação de Trabalho, então é a mesma estação de trabalho para o Servidor
dela. Um reapontamento para um Servidor *diferente* chega à fila desse Servidor como uma nova máquina
Pendente.

## Atualizando

**Um MSI mais novo se instala sobre um mais antigo. Esse é o procedimento inteiro.**

```powershell
msiexec /i TrustBridge-Workstation-1.1.0-x64.msi /qn
```

Nenhuma propriedade é necessária; o pacote novo lê os valores existentes da máquina antes de o produto
antigo ser removido e os grava de volta. Uma máquina atualizada é a mesma estação de trabalho:

| Sobrevive a uma atualização | Por quê |
|---|---|
| A **Chave da Estação de Trabalho** | Ela fica em um container CNG que nenhuma tabela do instalador cita |
| O **Cache de PIN**, o chaveiro dele, o conjunto de Autoridades Certificadoras Confiáveis em cache | Arquivos em `C:\ProgramData\TrustBridge\` que nenhum componente inclui |
| `ServerUrl`, `PkiLicense`, `InstallerKey` | Regravados a partir dos valores da própria máquina |
| A interface em pt-BR | Os assemblies satélites são substituídos, e não deixados para trás |

O Tray App é fechado pelo instalador durante o processo, então uma atualização não termina em
reinicialização. **Um downgrade é recusado**: voltar atrás é uma desinstalação de verdade, com tudo o
que a próxima seção descreve.

**Atualize primeiro o Servidor, depois as estações de trabalho, dentro de um mesmo ciclo de versão.**
Uma estação de trabalho cuja versão de protocolo é mais nova que a janela suportada pelo Servidor não
consegue se conectar até que o Servidor seja atualizado. Veja
[Operações](https://docs.lacunasoftware.com/articles/trustbridge/operations#ordem-de-atualização-primeiro-o-servidor-depois-a-frota).

## Removendo uma máquina

**Uma desinstalação é a saída da máquina da plataforma, e não é o inverso de uma atualização.**

```powershell
msiexec /x TrustBridge-Workstation-1.0.1-x64.msi /qn
```

Ou, sem o MSI à mão, pelo código do produto:

```powershell
$product = Get-ChildItem HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall |
    Where-Object { $_.GetValue('DisplayName') -eq 'TrustBridge Workstation' }
Start-Process msiexec -Wait -ArgumentList "/x $($product.PSChildName) /qn"
```

O que a remoção destrói, e nada mais destrói:

| | |
|---|---|
| A **Chave da Estação de Trabalho** | Excluída tanto do TPM quanto do repositório de software pelo verbo `purge-machine-identity` do próprio serviço, que a desinstalação agenda |
| `C:\ProgramData\TrustBridge\` | Toda a árvore de estado da máquina: Cache de PIN, chaveiro, conjunto de Autoridades Certificadoras Confiáveis em cache, âncoras |
| `HKLM\Software\TrustBridge` | Os três valores |
| O serviço, o Tray App, a entrada de inicialização automática | Remoção comum |
| `HKLM\Software\Policies\TrustBridge` | **Intocado.** Pertence ao mecanismo de diretivas |

A limpeza é executada em uma desinstalação de verdade e **nunca** na etapa de desinstalação de uma
atualização. Uma desinstalação é concluída mesmo quando a limpeza não é; nesse caso, o verbo grava uma
entrada bem visível no log Aplicativo, citando o que deixou para trás.

**A revogação no Servidor é o controle que não depende da cooperação da máquina.** Revogue uma máquina
removida no painel dela, na tela **Estações de Trabalho**, em `/admin/fleet`. **Reinstalar depois
produz uma máquina realmente nova**: ela volta à fila com uma nova impressão digital, e os titulares
dela digitam os PINs de novo.

## Quando uma instalação falha

| O que você vê | O que é | O que fazer |
|---|---|---|
| Código de saída **1603**, log cita `SERVER_URL` | A condição de inicialização | Passe `SERVER_URL=https://…`. O esquema não é opcional. |
| Código de saída **1603**, log diz que uma versão mais nova está instalada | Um downgrade | Remova antes o pacote mais novo, depois de ler *Removendo uma máquina*. |
| Reverte em *Starting services* | O serviço se recusou a iniciar: uma licença que o SDK não lê, uma `INSTALLER_KEY` que não pode ser interpretada ou um valor de Registro do tipo errado | O log de eventos Aplicativo cita o valor recusado. |
| Uma tela de arquivos em uso listando o Tray App | Uma atualização ou remoção interativa | Continue. O Tray é encerrado antes que qualquer arquivo seja tocado; não há reinicialização. |
| Concluída, mas a máquina não está na fila | Quase sempre a URL; às vezes um valor de diretiva sobrepondo o que você passou | Veja *Se a máquina nunca aparece na fila*, acima. |
| Concluída, mas todo certificado aparece como `UNTRUSTED` | Não há licença da PKI, ou ela expirou | Passe `PKI_LICENSE`, ou publique-a por Diretiva de Grupo, e então reinicie o serviço. |