Uma consola, muitos clientes

Se cuidas do Proxmox de outras pessoas, cada nó novo é o mesmo trabalho feito de maneira ligeiramente diferente. Cada cliente tem o seu país, fuso horário, chaves de root, disposição de discos, nomes de hosts e chave de subscrição. Erra uma dessas num nó acabado de instalar e descobres na primeira vez que alguém entra, ou na primeira vez que uma auditoria pergunta porque é que o relógio está uma hora desfasado.

Construí isto para um cliente com exatamente esse problema, e o que pediu era de uma simplicidade refrescante. Cada site é construído com o seu próprio esquema de nomes, a sua própria password de root e as suas próprias chaves SSH. Ninguém no site faz nada de esperto: montam um servidor no rack, ligam-no à VLAN certa e ligam a corrente. Ninguém recolhe números de série, e ninguém escreve um ficheiro de resposta por máquina. E um servidor acrescentado dessa maneira acaba no cluster já existente do site.

O que queriamO que o entrega aqui
nomes, password e chaves do próprio siteuma resposta preparada por site, escolhida pelo token desse site
ligar à VLAN certa, ligar a corrente, ir emboradescoberta por DNS, iPXE, e o Caddy a escolher o token pela sub-rede de origem
sem números de série, sem ficheiros de resposta por máquinaas respostas filtram só pelo produto; o site vem da rede
o servidor novo entra no cluster existentenão neste artigo: o PDM não tem hook de primeiro arranque, ver abaixo

Este artigo cobre os três primeiros: levar um servidor nu desde o ligar da corrente até um nó Proxmox instalado com as definições do site certo. Essa metade é a que aparece a quase toda a gente com mais de um site, MSP ou não, por isso vale a pena tê-la à parte. Entrar no cluster é outro trabalho, e a secção sobre o hook de primeiro arranque em falta explica porque é que o PDM ainda não o pode fazer por ti.

O Proxmox Datacenter Manager (PDM) 1.1 acrescentou a peça que faltava1. Agora pode servir de servidor de respostas para o instalador automático do Proxmox, de modo que uma máquina nua arranca, envia o que é, recebe de volta uma resposta preparada e instala-se sozinha sem ninguém à consola. Para um fornecedor de serviços geridos (MSP) que já usa o PDM como consola de gestão, esse é o sítio óbvio para guardar as definições de instalação de cada cliente.

O que não queres é um servidor PXE por cliente. Cada um deles é um servidor de Trivial File Transfer Protocol (TFTP), uma configuração DHCP, um conjunto de ficheiros de arranque e uma ISO para refazer cada vez que o Proxmox lança uma versão intermédia. Dez clientes são dez disso para manter atualizados. Isso não escala. O objetivo aqui é um parque PXE, uma imagem de arranque, um registo DNS e um PDM, com cada site a receber na mesma a sua própria resposta.

Um parque PXE para todos os sitessite110.10.50.0/24site210.20.50.0/24site310.30.50.0/24Caddy na 443entra o catch tokensai o token do site,escolhido pela sub-redePDMrespostas delimitadaspor token8443 no loopbackUma imagem de arranque, um registo DNS e um serviço DHCP para todos os sites
O desenho acabado. Todos os sites arrancam a mesma imagem. O Caddy descobre de que site veio um pedido pela sub-rede e entrega ao PDM o token desse site, e o PDM só oferece respostas associadas a esse token.

O PDM 1.1 faz a maior parte do caminho sozinho. Fica aquém em dois sítios, e vale a pena conhecer ambos antes de planear uma implementação à volta dele: não tem maneira de associar uma resposta a um site, e não tem maneira de dar a um nó novo um script de primeiro arranque. Este artigo prova ambos a partir do próprio código-fonte do PDM, contorna o primeiro e constrói tudo no PDM do meu laboratório com a versão 1.1.9, com o proxy endurecido para que as partes que guardam segredos fiquem fechadas.

O que o PDM 1.1 te dá

A funcionalidade vive em Remotes → Automated Installations e tem três partes: instalações, respostas preparadas e tokens de autenticação2. Uma resposta preparada é a versão do PDM do answer.toml do instalador, preenchida num formulário em vez de escrita à mão.

ParteO que fazO pormenor que importa
Respostas preparadaspaís, teclado, fuso horário, hash da password de root, chaves SSH, rede, disposição de discos, chave de subscrição, ação pós-instalaçãogeradas de novo a cada pedido
Filtros de alvodecidem que máquina recebe que respostaJSON Pointer para a informação de sistema do instalador, glob para o valor3
TemplatesMiniJinja nos campos de FQDN, email do administrador, IP, gateway e DNScontadores como installation_nr sobem cada vez que uma resposta é servida4
Tokens de autenticaçãoo instalador envia Authorization: Bearer <name>:<secret>um tipo de token separado dos tokens de API do PDM; cada resposta lista os tokens que aceita2
Instalaçõesum registo por pedido, com a informação de sistema completapassa de em curso a terminada quando o webhook pós-instalação responde
PermissõesSys.Audit para ver, Sys.Modify para alterarambas em /system/auto-installation4

O lado do instalador já existe há algum tempo. O comando proxmox-auto-install-assistant prepare-iso constrói uma ISO que vai buscar a resposta por HTTP, e desde a ISO do Proxmox VE 9.2 também consegue produzir o kernel, o initrd, a ISO e o boot.ipxe de que o iPXE precisa para arrancar tudo pela rede5.

Os contadores são a parte que um answer.toml isolado não tem. Uma resposta preparada numera cada host que constrói, onde um ficheiro estático teria de ser copiado por máquina. É um avanço real, e continua a ser uma primeira versão. O formulário ainda não está ao nível do ficheiro de resposta isolado6, e falta uma área por completo: não há script de primeiro arranque na 1.1, sob forma nenhuma7. Essa lacuna, e o site que não consegue usar como critério, são as duas secções seguintes.

Não consegue filtrar pelo site

O PDM escolhe uma resposta comparando filtros com a informação de sistema que o instalador envia. Por isso a pergunta é o que está nesse documento, porque o que lá não estiver não pode servir de critério.

ChaveO que contémPoderia identificar o site?
productfullname, product (pve, pbs, pmg), enable_btrfsnão
isorelease, isoreleasenão
dmisistema, motherboard e chassis: nome, número de série, UUID, SKU, asset tagsó se alguém tiver escrito o site na asset tag
network_interfacesuma lista de {link, mac}só através de um inventário que mantenhas tu

É tudo8,9. Não há endereço, nem hostname, nem opção DHCP, nada sobre onde a máquina está ligada.

Os campos da Desktop Management Interface (DMI) parecem prometedores até leres uns reais. Todas as instalações do meu laboratório voltaram com o nome de sistema Standard PC (Q35 + ICH9, 2009) e número de série e asset tag vazios. Os servidores reais preenchem-nos, mas com o que o fabricante lá pôs e não com o nome do teu cliente, e filtrar por números de série ou endereços MAC só funciona se mantiveres uma lista de todos os chassis que alguma vez vais instalar, que é exatamente a papelada que isto devia eliminar. Por host, sim. Por site, não.

Então, a que rede está a máquina ligada? O PDM nunca chega a saber. O instalador tem o seu lease DHCP na mão quando envia o pedido, e o único facto que um MSP sabe com certeza sobre um nó novo é precisamente o que fica para trás. Filtrar pelo endereço de origem, IPv4 ou IPv6, é um pedido de funcionalidade em aberto, e fui eu próprio que o abri, como bug 826310.

Há um segundo limite escondido nas regras de seleção, e o meu laboratório foi direto a ele.

Como o PDM escolhe uma resposta1. Token válido?ativo, não expiradonão401 ao fim de cerca de meio segundonão registado2. Respostas nesse tokenpela ordem do ficheiro, mais nada3. Todos os filtros correspondem?só strings, globs permitidosa primeiraresposta geradacada contador dela sobe 1nenhuma4. Omissão neste token?uma só por omissão em todo o PDMnão400: no answer file foundregistado em Installations
A seleção do PDM, a partir do código-fonte. O token é verificado primeiro e delimita tudo o que vem depois, incluindo a resposta por omissão.

O token é verificado primeiro, e só as respostas autorizadas para esse token são sequer consideradas, incluindo a por omissão4. O PDM permite exatamente uma resposta por omissão em todo o sistema. Por isso não podes dar a cada site um recurso próprio com a flag de omissão. O meu laboratório tinha uma resposta por omissão chamada fallback com um token próprio, e nunca foi servida uma única vez, porque nada envia esse token. Em vez disso, cada site precisa de um filtro que apanhe tudo no seu próprio token, como /product/product=*, posto em último lugar no ficheiro.

Mais duas coisas do mesmo código que vale a pena teres na cabeça quando estiveres a depurar:

  • Ganha a primeira correspondência, pela ordem do ficheiro, e uma segunda correspondência só regista um aviso. É a regra desde a 1.1.111.
  • Um filtro só corresponde a strings. /product/enable_btrfs é um booleano e nunca corresponde a nada, e um array precisa de um índice, como em /network_interfaces/0/mac.

Na 1.1.9, um token desconhecido ou expirado recebe um 401 depois de um atraso deliberado de cerca de meio segundo e não deixa registo. Um token válido sem nada que corresponda recebe um 400 com o corpo no answer file found, e essa tentativa fica registada, com a informação de sistema completa. Esse registo é a maneira mais rápida de ler os números de série e endereços MAC reais de um chassis novo antes de escreveres um filtro para ele.

Não consegue correr um script de primeiro arranque

O próprio instalador suporta um hook de primeiro arranque. Uma resposta pode levar uma secção [first-boot] com source = "from-iso" ou "from-url", uma ordem de before-network, network-online ou fully-up, e uma impressão digital de certificado opcional9. prepare-iso --on-first-boot embute um script na ISO para o caso from-iso.

O PDM nunca envia essa secção. Nem uma vez. O tipo de resposta do próprio instalador tem o campo, first_boot: Option<FirstBootHookInfo>12. A resposta preparada do PDM não tem campo nenhum para isso, e o código que constrói a resposta a partir dela escreve first_boot: None incondicionalmente4. Não há nada no formulário, nada na API e nada no ficheiro de configuração que pudesses acrescentar à mão. É um pedido de funcionalidade em aberto, o bug 7699, aberto em junho de 2026 e ainda sem responsável quando isto foi escrito7. Quase cinco meses depois não teve nenhuma resposta da Proxmox, e o 8263 também não. Esse silêncio é a parte preocupante. Quem se deu ao trabalho de escrever como o teu produto podia ser melhor merece uma resposta, mesmo que a resposta seja não, e isso é cortesia profissional elementar. Mais ainda quando quem escreve são clientes pagantes e parceiros, que já estão a pôr dinheiro no produto antes de lhe porem também o seu tempo.

E o script na ISO não te salva. O instalador só configura o serviço de primeiro arranque if let Some(first_boot) = &answer.first_boot, e esse é o único caminho que alguma vez lê o ficheiro embutido13. O prepare-iso não dá nenhum aviso quando embutes um script que nenhuma resposta vai alguma vez pedir. Fica na ISO e não faz nada.

A lacuna do primeiro arranqueScript na ISOprepare-iso --on-first-bootResposta do PDMfirst_boot: None, sempreInstaladorconfigura o hook de primeiro arranquesó se a resposta tiver[first-boot]o script fica na ISOe nunca corre, sem nenhum aviso
As duas metades chegam ao instalador, e a metade que vem do PDM nunca pede o hook. O script na ISO é peso morto.

Isso importa mais para um MSP do que para qualquer outra pessoa. Um nó saído do instalador é um sistema nu com uma password de root em hash e algumas chaves SSH. Não é um remote do PDM, não está num cluster, e não tem nada da tua monitorização, repositórios ou armazenamento. No meu laboratório os três nós terminaram todos e deram sinal, e o remote SITEA no PDM ainda teve de ser acrescentado à mão depois.

Por isso, seja o que for que uses para acabar um nó, seja Ansible ou outra coisa, tem de ser disparado de fora: pelo webhook pós-instalação, por uma tarefa que vigia a lista de Installations, ou por uma pessoa. Deixo isso por aqui. Este artigo é sobre pôr um único parque PXE a servir todos os sites, e a lacuna do primeiro arranque é um limite a ter em conta no planeamento, não um que eu vá tapar aqui.

O token é o site

O PDM não consegue ver o site, mas delimita as respostas por token, e um token é só um cabeçalho. Quem define o cabeçalho escolhe que conjunto de respostas o instalador pode obter. É esse o truque todo.

Por isso põe à frente do PDM algo que saiba de onde veio o pedido:

  1. A imagem de arranque leva um catch token, catch-all:not-a-secret, que é igual em todas as imagens e está publicado aqui mesmo. Não é um token do PDM e não abre nada sozinho.
  2. Um reverse proxy Caddy à frente do PDM olha para a sub-rede de origem de um pedido de resposta que leve o catch token, e substitui o cabeçalho pelo token real desse site.
  3. O PDM vê site2-2026q4:<secret> e só oferece as respostas do site2.

O segredo nunca chega perto da imagem de arranque, por isso uma pen USB perdida ou uma ISO copiada não dão nada a ninguém. Rodar o token de um site é uma alteração no Caddy, não uma reconstrução da imagem. E acrescentar um site é uma linha de configuração do Caddy e um token novo no PDM.

Isto assenta em o endereço de origem ser honesto, o que é uma propriedade da tua rede, não do proxy. Esse compromisso e os outros estão expostos em «O que falta decidir», mais abaixo.

Como o instalador encontra o PDM sem um URL embutido

Uma imagem para todos os sites só funciona se a imagem também não levar o endereço do PDM. O instalador procura o URL da resposta em três sítios, por ordem14:

Onde o instalador encontra o URL da resposta1. URL embutido na ISO?prepare-iso --urlsimusado, DHCP e DNS nunca consultadosuma imagem por PDM: evitado aquinão2. Opção DHCP 250?lida do lease do instaladorsimusada, com a opção 251 para aimpressão digital: aqui não enviadanão, ou qualquer erro DHCP3. Consulta DNS TXTdomínio de pesquisa do resolv.confproxmox-auto-installer.example.docURL e impressão digital, ambos do DNS
A ordem que o instalador segue. Deixa o URL fora da imagem e não envies a opção 250, e todos os sites caem no DNS.
RegraO que o código fazO que significa para ti
Ordemum URL na ISO ganha; senão DHCP; qualquer falha de DHCP recua para DNS14constrói a imagem sem --url, e não envies a opção 250 em lado nenhum
Nomes dos registosproxmox-auto-installer.<search domain> para o URL, proxmox-auto-installer-cert-fingerprint.<search domain> para a impressão digitaluma zona, dois registos TXT
Domínio de pesquisaa primeira linha search de /etc/resolv.conf, dividida num único espaçodistribui exatamente um domínio; dois tornam-se um nome inválido
Sem domíniofalha com Could not find search domain in resolv.conf.verifica que a opção DHCP 15 ou 119 está a ser enviada
Valor TXTdig txt +short, todas as " removidas, depois aparadoum valor TXT dividido em várias strings deixa um espaço no URL; mantém-no numa string só
Impressão digitaltirada do DNS só quando o URL também veio do DNS e não há nenhuma embutidapublica a impressão digital do certificado do PDM, que o Caddy também serve
Tokenenviado como Authorization: Bearer <token>, guardado em texto simples na ISO9é por isso que a imagem só leva o catch token

O certificado que o instalador verifica é o que responder na 443. Neste desenho o Caddy serve lá o próprio certificado do PDM, por isso um cliente vê na 443 o mesmo certificado que o PDM tem na 8443, e há uma só impressão digital para publicar.

Construir: PDM, ficheiros de arranque e DNS

Os exemplos usam o domínio example.doc e três sites, 10.10.50.0/24, 10.20.50.0/24 e 10.30.50.0/24. .doc não é um domínio de topo real, por isso substitui pelo teu. O PDM, o Caddy, o dnsmasq e os ficheiros de arranque vivem todos num host, pdm.example.doc em 10.10.50.10, e os sites remotos chegam lá através de um relay DHCP nos seus gateways. A gestão vive em 10.99.0.0/24 e, como tal, é a única rede que alguma vez vê a interface web do PDM.

Tokens e respostas no PDM

Em Remotes → Automated Installations → Authentication Tokens, acrescenta um token por site e dá-lhe uma validade que corresponda à tua janela de implementação. O nome não é secreto, e vais vê-lo nos logs, por isso faz com que diga alguma coisa: site1-2026q4. Copia o segredo quando for mostrado.

Depois acrescenta uma resposta preparada por site e por produto, autorizada apenas no token desse site:

Camposite1, Proxmox VE
Token autorizadosite1-2026q4
Filtro de alvo/product/product=pve
País, teclado, fuso horáriogb, en-gb, Europe/London
Acesso rootchaves SSH, mais uma password definida no formulário, que o PDM guarda e envia apenas como hash4
RedeDHCP, nomes de interfaces fixados
FQDN{{ product.product }}-site1-{{ installation_nr }}.example.doc
Discoa tua disposição, por exemplo um espelho ZFS sobre dois discos nomeados
Webhook pós-instalaçãoURL base https://pdm.example.doc, com a impressão digital do certificado do PDM

O contador sobe cada vez que uma resposta é servida, incluindo as repetições, por isso os nomes podem saltar números. O contador do meu laboratório está em 4 depois de três instalações terminadas. Se precisas de nomes previsíveis, usa FQDN from DHCP e põe o nome do host na reserva DHCP.

O URL base do webhook é a única definição que tem de mudar para este desenho. O natural é apontá-lo para o próprio PDM na porta 8443, que era como o meu laboratório o tinha, e a 8443 está prestes a ser fechada. Aponta-o para o Caddy.

Os ficheiros de arranque

Em qualquer host Proxmox VE ou Debian com o repositório do Proxmox:

apt install proxmox-auto-install-assistant xorriso
mkdir -p /srv/www/pve-9.2
proxmox-auto-install-assistant prepare-iso proxmox-ve_9.2-1.iso \
  --fetch-from http \
  --answer-auth-token 'catch-all:not-a-secret' \
  --pxe-loader ipxe \
  --output /srv/www/pve-9.2/

Sem --url, porque o DNS fornece-o. --pxe-loader ipxe implica --pxe, e com --pxe a saída tem de ser um diretório que já exista15. Recebes quatro ficheiros: vmlinuz, initrd.img recomprimido de zstd para gzip porque o iPXE não consegue carregar um initrd zstd, a ISO preparada com /boot removido, e um menu boot.ipxe que arranca por omissão a instalação automática ao fim de dez segundos e se refere aos outros pelo nome relativo15. Mantém os quatro no mesmo diretório.

Cada alvo precisa de memória suficiente para guardar o kernel, o initrd e a ISO inteira. As notas do Proxmox VE 9.2 apontam «at least 6 GiB of available memory on the host»5. As mesmas notas indicam um problema conhecido do kernel da ISO 9.2 com controladores megaraid_sas e alguns discos NVMe em modo JBOD (just a bunch of disks), com o conselho de instalar a partir da ISO 9.1 e atualizar5. Testa o teu hardware antes de lhe confiares o caminho pela rede.

Os registos DNS

Na zona que corresponde ao único domínio de pesquisa que o DHCP distribui:

$ORIGIN example.doc.
pdm                                      IN A    10.10.50.10
proxmox-auto-installer                   IN TXT  "https://pdm.example.doc/api2/json/auto-install/answer"
proxmox-auto-installer-cert-fingerprint  IN TXT  "63:C4:D6:...:85:07"

A impressão digital é a do próprio certificado do PDM:

openssl x509 -in /etc/proxmox-datacenter-manager/auth/api.pem -noout -fingerprint -sha256

Verifica-os da maneira que o instalador o fará:

dig txt +short proxmox-auto-installer.example.doc @10.10.50.10
# one quoted string, nothing split

Caddy, a única porta para o PDM

A API do PDM escuta em [::]:8443, e isso é uma constante compilada no binário, não uma definição16. Não a podes ligar ao loopback. Por isso o Caddy torna-se a única entrada, e a firewall garante-o.

As rotas do Caddy à frente do PDMPEDIDOO QUE ACONTECEPOST de resposta, sub-rede de site, catch tokenreescrito com o token desse sitePOST de post-hook, sub-rede de siteAuthorization retirado, segueinterface web ou API, sub-rede de gestãopassa intacto, login do PDMtudo o resto, de qualquer ladoabortado, nunca chega ao PDMporta 8443, de fora da máquinadescartado pelo nftables
Cada pedido que o Caddy vê acaba num de cinco sítios. Só os três primeiros chegam ao PDM.

O PDM tem exatamente duas rotas que funcionam sem login no PDM: POST /api2/json/auto-install/answer com um token de instalador, e POST …/installations/{uuid}/post-hook com o token de uso único no corpo4. São as únicas duas a que uma rede de provisionamento deve alguma vez chegar.

Usa o Caddy 2.11.1 ou posterior. A 2.11.1 corrigiu um bypass do path matcher, CVE-2026-27587, que é exatamente o tipo de filtragem por caminho em que isto assenta17. O pacote do próprio Debian 13 é a 2.6.2, por isso tira-o do trixie-backports, que traz a 2.11.2, ou do repositório do próprio Caddy18.

O Caddyfile, /etc/caddy/Caddyfile:

{
	# the admin API on a socket only root can open, never on TCP
	admin unix//run/caddy/admin.sock|0600
	auto_https disable_redirects
	servers {
		protocols h1 h2
	}
}

# PDM itself, on the loopback, trusted by its own certificate
(pdm_upstream) {
	reverse_proxy https://[::1]:8443 {
		transport http {
			tls_trust_pool file /etc/proxmox-datacenter-manager/auth/api.pem
			tls_server_name pdm.example.doc
		}
	}
	log_append pdm_status {http.reverse_proxy.status_code}
}

# one site: name, subnet, PDM token name, PDM token secret
(site) {
	@{args[0]} {
		method POST
		path /api2/json/auto-install/answer
		remote_ip {args[1]}
		header Authorization "Bearer catch-all:not-a-secret"
	}
	handle @{args[0]} {
		log_append site {args[0]}
		log_append pdm_token {args[2]}
		request_header Authorization "Bearer {args[2]}:{args[3]}"
		import pdm_upstream
	}
}

pdm.example.doc, 10.10.50.10 {
	tls /etc/proxmox-datacenter-manager/auth/api.pem /etc/proxmox-datacenter-manager/auth/api.key

	import site site1 10.10.50.0/24 site1-2026q4 {env.PDM_SECRET_SITE1}
	import site site2 10.20.50.0/24 site2-2026q4 {env.PDM_SECRET_SITE2}
	import site site3 10.30.50.0/24 site3-2026q4 {env.PDM_SECRET_SITE3}

	@post_hook {
		method POST
		path /api2/json/auto-install/installations/*/post-hook
		remote_ip 10.10.50.0/24 10.20.50.0/24 10.30.50.0/24
	}
	handle @post_hook {
		request_header -Authorization
		import pdm_upstream
	}

	# the PDM web UI and API, from the management network only
	@mgmt remote_ip 10.99.0.0/24
	handle @mgmt {
		import pdm_upstream
	}

	# anything else, from anywhere, never reaches PDM
	handle {
		abort
	}

	log {
		output file /var/log/caddy/pdm.log
		format filter {
			request>headers>Csrfpreventiontoken replace REDACTED
		}
	}
}

# boot files, to the sites and management only
http://:80 {
	@hidden path_regexp /\.
	handle @hidden {
		abort
	}
	@boot remote_ip 10.10.50.0/24 10.20.50.0/24 10.30.50.0/24 10.99.0.0/24
	handle @boot {
		root * /srv/www
		file_server
	}
	handle {
		abort
	}
}

As partes que fazem trabalho de segurança, e porque está lá cada uma:

LinhaPorquê
header Authorization "Bearer catch-all:not-a-secret" no matcher do sitesem ela, qualquer POST de uma sub-rede de site recebe o token real; um pedido tem de vir da sub-rede certa e levar o catch token
request_header Authorization …define o cabeçalho, sobrescrevendo o que o cliente enviou, por isso um token forjado é substituído, nunca reencaminhado19
remote_ipo par imediato; não ponhas NAT nem balanceador de carga entre os instaladores e o Caddy20
blocos handle com nomemantidos pela ordem em que estão escritos e mutuamente exclusivos, por isso o handle { abort } simples tem a última palavra21
@mgmta interface e a API completas do PDM, intactas, para que o login, os tokens de API e os cookies do próprio PDM funcionem normalmente; uma sub-rede de site não recebe nada disso
admin unix//…|0600a API de administração usa por omissão TCP localhost:2019, sem autenticação22
protocols h1 h2o Caddy escuta por omissão em UDP 443 para HTTP/322; isto desliga-o em vez de deixar uma porta que ninguém quis abrir
@hiddeno file_server serve todos os ficheiros debaixo da sua raiz, incluindo os ficheiros com ponto, e o hide está documentado como não sendo uma fronteira de segurança23
Csrfpreventiontoken replace REDACTEDo Caddy oculta Authorization e Cookie no seu log de acessos por omissão, mas não o cabeçalho CSRF do PDM24

O path matcher é mais tolerante do que o PDM, que é o sentido certo. O Caddy limpa o caminho, descodifica o percent-encoding, junta barras repetidas e ignora maiúsculas antes de comparar20. Por isso //answer, %61nswer e ANSWER contam todos como a rota de resposta, e uma variante /api2/extjs/… ou uma barra final não correspondem a uma rota de site e caem no abort.

Há duas escolhas ali que precisam de explicação.

O Caddy serve o certificado do PDM, diretamente dos ficheiros do PDM. O Caddy lê api.pem e api.key onde o PDM os guarda, por isso os instaladores, o webhook e um browser veem todos o certificado que o PDM apresenta na 8443, e não há segunda cópia a desatualizar-se. A maneira óbvia de lhe dar esse acesso é acrescentar o utilizador caddy ao www-data. No meu laboratório verifiquei aquilo a que essa pertença ao grupo dá realmente acesso, testando cada ficheiro como o utilizador caddy:

Ficheiro em /etc/proxmox-datacenter-manager/Legível pelo caddy no www-data
remotes.shadow, as credenciais de todos os remotes geridossim
autoinst/tokens.shadow, todos os segredos dos tokens de instaladorsim
auth/api.key, auth/csrf.keysim
access/user.cfg, subscriptions/sim

Nada nessa lista deve estar perto de um proxy web. Um bug no proxy seria então um comprometimento de todos os clusters que o PDM gere.

Por isso o Caddy fica fora do www-data e recebe uma ACL exatamente nos dois ficheiros de que precisa, mais permissão para atravessar os dois diretórios acima deles sem os listar:

#!/bin/sh
# /usr/local/sbin/pdm-cert-acl
# let Caddy read PDM's certificate and key in place, and nothing else of PDM's
set -e
D=/etc/proxmox-datacenter-manager; A=$D/auth
setfacl -m u:caddy:x "$D" "$A"
setfacl -m u:caddy:r "$A/api.pem" "$A/api.key"

Testado como o utilizador caddy no laboratório depois de o correr:

Caminhocaddy
auth/api.pem, auth/api.keyconsegue ler
auth/csrf.key, auth/authkey.key, auth/authkey.pubnão consegue ler
remotes.shadow, remotes.cfg, autoinst/tokens.shadow, access/user.cfgnão consegue ler
listar auth/recusado

O senão é a renovação. O PDM escreve um certificado renovado num ficheiro novo e renomeia-o para o lugar, e um ficheiro novo não traz a ACL do antigo. Por isso, quando o PDM renova, o systemd repõe a ACL e recarrega o Caddy, sem ninguém envolvido.

Uma verificação de que o certificado e a chave pertencem um ao outro, porque uma renovação escreve-os um de cada vez:

#!/bin/sh
# /usr/local/sbin/pdm-cert-pair-ok
# exit 0 only when PDM's certificate and key belong together
d=/etc/proxmox-datacenter-manager/auth
c=$(openssl x509 -noout -pubkey -in "$d/api.pem") || exit 1
k=$(openssl pkey -pubout -in "$d/api.key") || exit 1
[ "$c" = "$k" ]

Uma unidade path a vigiar os dois ficheiros, e o serviço que ela arranca:

# /etc/systemd/system/caddy-pdm-cert.path
[Unit]
Description=Watch the PDM certificate and key for renewal

[Path]
PathChanged=/etc/proxmox-datacenter-manager/auth/api.pem
PathChanged=/etc/proxmox-datacenter-manager/auth/api.key
Unit=caddy-pdm-cert.service

[Install]
WantedBy=multi-user.target

# /etc/systemd/system/caddy-pdm-cert.service
[Unit]
Description=Let Caddy read the renewed PDM certificate in place, then reload Caddy

[Service]
Type=oneshot
ExecCondition=/usr/local/sbin/pdm-cert-pair-ok
ExecStart=/usr/local/sbin/pdm-cert-acl
ExecStart=/usr/bin/systemctl try-reload-or-restart caddy.service
apt install acl
systemctl daemon-reload
systemctl enable --now caddy-pdm-cert.path

O override mais abaixo corre o mesmo script de ACL antes de cada arranque do Caddy, por isso uma renovação enquanto o Caddy estava parado nunca é perdida.

Os pormenores que o fazem funcionar, cada um verificado:

PeçaPorquê
os dois ficheiros vigiadosa primeira escrita dispara a unidade; a condição salta-a enquanto o par não corresponder, e a segunda escrita volta a dispará-la com um par que corresponde
ExecConditionuma condição falhada salta a execução em vez de a dar como falhada, por isso uma renovação a meio nunca chega ao Caddy25
PathChangeddispara quando um ficheiro vigiado que estava aberto para escrita é fechado26; no laboratório também disparou quando um ficheiro novo foi renomeado por cima do antigo
o script de ACL em cada execuçãoum ficheiro renomeado para o lugar não tem ACL, por isso o Caddy não o conseguia ler até o script voltar a correr
try-reload-or-restartrecarrega o Caddy se estiver a correr e não faz nada se não estiver
reload --force na unidade do Caddysem --force, o Caddy vê a mesma configuração e continua a servir o certificado antigo

Essa última linha não é um palpite. Num contentor descartável com o Caddy 2.11.7 troquei o ficheiro do certificado por trás de um servidor em execução: um caddy reload simples continuou a servir o certificado antigo, e caddy reload --force serviu o novo. A unidade empacotada já recarrega com --force27, por isso mantém essa linha se fizeres override do ExecReload.

No laboratório substituí o api.key e o api.pem do PDM da maneira que uma renovação o faz, escrevendo ficheiros novos e renomeando-os por cima dos antigos. Logo a seguir ao rename, o api.key não tinha entrada de ACL para o caddy. Em quatro segundos a unidade path tinha disparado, a ACL estava de volta nos dois ficheiros, e o Caddy tinha recarregado no lugar com o mesmo ID de processo.

O nome do token e o segredo ficam separados. O nome vai no Caddyfile, onde é registado. O segredo vai num ficheiro de ambiente que só o root pode ler, e o Caddy lê-o através de {env.*} no momento do pedido.

Regista que token foi usado, nunca o segredo

A primeira versão disto no meu laboratório deixava fugir o segredo. A unidade empacotada do Caddy arranca-o como caddy run --environ, e --environ imprime o ambiente inteiro antes de arrancar28,27. Cada reinício punha o token do site no journal em texto claro: oito linhas disso quando as contei. Nada no log de acessos, nada nos logs do próprio PDM, tudo vindo daquela única flag.

Para onde vão o segredo e o nome do tokenO SEGREDOpdm-secrets.envsó root, 0600ambiente do Caddy{env.PDM_SECRET_SITE1}cabeçalho Authorizationsó o salto de loopback até ao PDMO NOMElinha import noCaddyfilelog de acessos, cada pedido de resposta"pdm_token":"site1-2026q4"NUNCA ESCRITO EMo journal--environ retiradoa API de administraçãosocket unix, 0600um dump da configuraçãosó o placeholder
O segredo tem um trabalho e um caminho. O nome é o que registas.

Por isso o ficheiro de segredos guarda segredos e mais nada:

install -m 0600 /dev/null /etc/caddy/pdm-secrets.env
printf 'PDM_SECRET_SITE1=%s\nPDM_SECRET_SITE2=%s\nPDM_SECRET_SITE3=%s\n' \
  '<secret1>' '<secret2>' '<secret3>' > /etc/caddy/pdm-secrets.env

e o override da unidade tira o --environ e dá uma casa ao socket de administração:

# systemctl edit caddy
[Service]
EnvironmentFile=/etc/caddy/pdm-secrets.env
RuntimeDirectory=caddy
RuntimeDirectoryMode=0700
# PDM's certificate and key, read where PDM keeps them
ExecStartPre=+/usr/local/sbin/pdm-cert-acl
# the access log directory and its files belong to Caddy
ExecStartPre=+/usr/bin/install -d -o caddy -g caddy -m 0750 /var/log/caddy
ExecStartPre=+/usr/bin/chown -R caddy:caddy /var/log/caddy
ExecStart=
ExecStart=/usr/bin/caddy run --config /etc/caddy/Caddyfile
ExecReload=
ExecReload=/usr/bin/caddy reload --config /etc/caddy/Caddyfile --force

O + corre essas linhas como root, antes de o Caddy arrancar com o seu próprio utilizador. As linhas do log importam assim que outra coisa mexa em /var/log/caddy: um log rodado pelo root, ou um ficheiro criado à mão durante os testes, deixa o Caddy incapaz de abrir o seu próprio log de acessos. No laboratório pus o pdm.log como root:root e reiniciei o Caddy; voltou como caddy:caddy e o Caddy não registou erros de permissões.

Reinicia em vez de recarregar depois de o editar, porque um reload não volta a ler o ambiente. Usa {env.NAME}, nunca {$NAME}: a segunda forma é substituída quando o Caddyfile é adaptado, por isso o segredo acaba na configuração JSON, no ficheiro de autosave e em tudo o que os despeje29. O socket de administração também importa aqui. {env.*} resolve qualquer coisa do ambiente do processo sem lista de autorizações, por isso quem conseguir carregar uma configuração através de uma API de administração em TCP pode pôr o Caddy a devolver-lhe um segredo30.

Cada linha de resposta no log de acessos indica agora o site e o token, com o próprio cabeçalho ocultado. Do laboratório, onde ambos se chamam siteA:

{"site":"siteA","pdm_token":"siteA","pdm_status":400,"status":400,
 "request":{"headers":{"Authorization":["REDACTED"]}}}

Verifiquei-o em vez de confiar. Numa cópia em podman desta configuração com segredos fictícios, e depois no laboratório, enviei respostas por todos os caminhos de que me lembrei: normal, com logging de debug ligado, upstream em baixo para um 502, um reload e um reinício. Depois contei cada segredo no journal, no log de acessos, nos diretórios de configuração e de dados do Caddy e no JSON adaptado. Todas as contagens deram zero. A execução de controlo, a mesma configuração arrancada com --environ, imprimiu o segredo duas vezes.

Duas ressalvas desse teste. Com debug ligado, o Caddy regista toda a sua configuração adaptada, por isso o catch token e os placeholders {env.*} aparecem lá; os valores por trás deles não apareceram. Mantém o debug desligado em produção na mesma. E se um segredo já passou por um journal, como o meu, gera-o de novo no PDM e atualiza o ficheiro; apagar linhas de log não é a solução.

A firewall: a 8443 nunca sai da máquina

O meu laboratório não tinha firewall nenhuma, por isso a 8443 respondia a todos os hosts da rede de provisionamento e todas as regras do Caddyfile podiam ser contornadas. Fecha-a. nftables, com drop por omissão:

#!/usr/sbin/nft -f
flush ruleset

define SITES = { 10.10.50.0/24, 10.20.50.0/24, 10.30.50.0/24 }
define MGMT  = { 10.99.0.0/24 }

table inet filter {
	chain input {
		type filter hook input priority filter; policy drop;

		iifname "lo" accept
		ct state established,related accept
		ct state invalid drop
		meta l4proto { icmp, ipv6-icmp } accept

		# PDM's API listens on [::]:8443 and cannot be rebound
		tcp dport 8443 counter drop

		ip saddr $MGMT tcp dport { 22, 80, 443 } accept

		udp dport { 67, 69 } accept
		ip saddr $SITES meta l4proto { tcp, udp } th dport 53 accept
		ip saddr $SITES tcp dport { 80, 443 } accept
	}
	chain forward {
		type filter hook forward priority filter; policy drop;
	}
}

As ligações do PDM aos seus remotes são de saída, por isso fechar a 8443 à entrada não muda nada aí. Carrega um ruleset novo com rollback temporizado da primeira vez, para que um erro te custe noventa segundos e não uma ida à consola:

systemd-run --unit=nft-rollback --on-active=90 /usr/sbin/nft flush ruleset
nft -f /etc/nftables.conf
# still connected? then:
systemctl stop nft-rollback.timer && systemctl enable nftables

No laboratório, depois de tudo isto:

VerificaçãoResultado
8443 a partir da rede de gestãosem ligação; o contador de drop a subir
interface web do PDM através do Caddy na 443, a partir da gestãofaz login e funciona
interface web do PDM a partir de um endereço de siteabortado
POST de resposta de um site com o catch tokenchega ao PDM com o token do site: uma sonda deliberadamente sem correspondência recebeu 400 no answer file found
a mesma sonda diretamente ao PDM com um token inventado401
POST de resposta sem o catch token, ou como /api2/extjs/…abortado
ficheiros onde vivem os segredos do PDM, lidos como caddynenhum legível
o segredo do site no journal, no log de acessos ou nos dados do Caddy desde a alteração0

DHCP, iPXE e o ciclo

O firmware do servidor só consegue ir buscar o seu primeiro ficheiro por TFTP, por isso o TFTP serve o pequeno loader do iPXE e o iPXE vai buscar tudo o resto por HTTP. A armadilha é que o iPXE envia o seu próprio pedido DHCP, e um servidor que lhe responda outra vez com ipxe.efi põe a máquina a andar em círculos para sempre. O servidor DHCP tem de distinguir o firmware do iPXE.

Porque é que uma resposta DHCP simples entra em cicloResposta simples: cicloo firmware pede um ficheiro de arranqueresposta: ipxe.efio iPXE arranca e volta a pedirmesma resposta: ipxe.efio servidor não distingue o firmwaredo iPXE, por isso nunca avançaReconhece o iPXE: funcionao firmware pede um ficheiro de arranquenão é iPXE: ipxe.efi por TFTPo iPXE volta a pedir, com a opção 175resposta: o URL do boot.ipxe, por HTTPkernel, initrd e ISO, depois instala
O mesmo pedido duas vezes recebe a mesma resposta duas vezes. A opção 175, que só o iPXE envia, é como o servidor distingue o segundo pedido do primeiro.
Servidor DHCPComo quebra o ciclo
dnsmasqmarca os pedidos que levam a opção 175, que só o iPXE envia, e dá-lhes o URL HTTP31
ISC dhcpdif exists user-class and option user-class = "iPXE"32
FortiGateo campo filename aceita um só valor, por isso constrói um loader iPXE com o URL embutido e serve-o a tudo

O dnsmasq, a servir a sua própria rede e as outras duas através de relays, só com reservas:

# /etc/dnsmasq.d/pxe.conf
local=/example.doc/
domain=example.doc
address=/pdm.example.doc/10.10.50.10
txt-record=proxmox-auto-installer.example.doc,"https://pdm.example.doc/api2/json/auto-install/answer"
txt-record=proxmox-auto-installer-cert-fingerprint.example.doc,"63:C4:D6:...:85:07"

dhcp-authoritative
dhcp-range=set:site1,10.10.50.0,static,255.255.255.0,1h
dhcp-range=set:site2,10.20.50.0,static,255.255.255.0,1h
dhcp-range=set:site3,10.30.50.0,static,255.255.255.0,1h
dhcp-option=tag:site1,option:router,10.10.50.1
dhcp-option=tag:site2,option:router,10.20.50.1
dhcp-option=tag:site3,option:router,10.30.50.1
dhcp-option=option:dns-server,10.10.50.10
dhcp-option=option:domain-search,example.doc

dhcp-match=set:ipxe,175
dhcp-match=set:efi64,option:client-arch,7
dhcp-match=set:efi64,option:client-arch,9
dhcp-boot=tag:efi64,tag:!ipxe,ipxe.efi
dhcp-boot=tag:ipxe,http://pdm.example.doc/pve-9.2/boot.ipxe
# no option 250 anywhere: DNS discovery depends on it

enable-tftp
tftp-root=/srv/tftp
tftp-secure
# TFTP block-size ceiling: lower it for an IPsec or other tunnel in the path
tftp-mtu=1500

# dhcp-host=<mac>,<ip inside that site's /24>,<hostname>
dhcp-host=aa:bb:cc:dd:ee:01,10.10.50.21,pve01
dhcp-host=aa:bb:cc:dd:ee:02,10.20.50.21,pve01

static quer dizer sem pool: só as máquinas reservadas recebem endereço, o que mantém estranhos fora do caminho do instalador. O endereço de cada reserva tem de estar dentro do /24 do seu próprio site, porque esse endereço é o que o Caddy usa para escolher o token. Um nó reservado na sub-rede errada recebe a resposta do site errado, ou nada.

As reservas são uma lista de endereços MAC, e isso é papelada por máquina, exatamente do tipo que o cliente não queria. Se ligar e arrancar é mesmo o requisito, dá a cada VLAN de provisionamento uma pequena gama dinâmica, por exemplo dhcp-range=set:site1,10.10.50.100,10.10.50.150,255.255.255.0,1h. O site continua a vir da sub-rede, por isso o Caddy continua a escolher o token certo, e o template de FQDN com installation_nr dá nome ao nó. O preço é a primeira linha de «O que falta decidir»: qualquer coisa ligada a essa VLAN pode agora ir buscar a resposta do site, por isso a própria VLAN passa a ser o portão.

O dnsmasq negoceia o tamanho de bloco TFTP com o cliente. Se o deixares, limita-o ao MTU da sua própria interface31, o que funciona até o caminho para um site ser mais pequeno do que o link em que o dnsmasq está. Por isso a configuração declara o teto como tftp-mtu=1500 em vez de o herdar. Isso põe o número à frente de quem cuida de um site atrás de um túnel IPsec ou de qualquer outra coisa que coma espaço ao pacote, e essa pessoa baixa-o para o que o caminho realmente aguenta em vez de o descobrir por uma transferência que encrava a meio. Se uma ROM de NIC se portar mal quando a opção é sequer concedida, tftp-no-blocksize desliga a negociação.

Copia o ipxe.efi do pacote ipxe do Debian para /srv/tftp, com o utilizador dnsmasq como dono, porque o tftp-secure recusa tudo o resto. Prefere UEFI. O Secure Boot precisa de um iPXE assinado, por isso ou configuras isso ou desligas o Secure Boot para a instalação e voltas a ligá-lo depois.

Arrancar, observar e o que avaria

Testa com uma máquina virtual numa rede de site antes de tocares em hardware: firmware UEFI, 8 GiB de memória e uma NIC nessa VLAN reproduzem a cadeia inteira.

O que acontece no arranqueServidor alvoarranque de rede UEFI6 GiB ou mais1. DHCP e TFTPum lease, um domínio de pesquisa, depois ipxe.efi2. HTTP na porta 80boot.ipxe, vmlinuz, initrd.img e a ISO, para a memória3. DNSdois registos TXT: URL da resposta e impressão digital do PDM4. Caddy na 443, depois PDMa resposta agora, o webhook depois do reinício
Quatro conversas separadas, cada uma com o seu sítio onde olhar quando falha.

E tudo por ordem, desde ligar a corrente até uma instalação que o PDM marca como Finished:

Do ligar da corrente à instalação completaAlvodnsmasq, :80Caddy :443PDMDHCP: um leaseTFTP: ipxe.efio iPXE volta a pedirHTTP: kernel, initrd, ISOinstalador: um domínioDNS: dois registos TXTPOST, catch tokentoken do siteem cursoa resposta gerada, via Caddyinstala no discowebhook, token de uso únicoAuthorization retiradoFinishedreinicia; primeiro arranqueativa a chave
Todos os passos, por ordem. O webhook é enviado pelo instalador antes do reinício, por isso Finished quer dizer instalado, não arrancado; a chave de subscrição é ativada depois, no primeiro arranque.
PassoO que aconteceOnde olhar
1o firmware recebe ipxe.efi por TFTP, o iPXE recebe boot.ipxe por HTTPjournalctl -u dnsmasq, o log do Caddy
2ao fim de dez segundos o menu arranca a entrada automática; descarregam-se o kernel, o initrd e a ISOquatro GET, um deles de cerca de 1,6 GB
3o instalador obtém um lease, lê o domínio de pesquisa, consulta os dois registos TXT/tmp/fetch_answer.log no alvo
4POST para o Caddy, token trocado, o PDM escolhe uma respostao log do Caddy indica o token; o PDM mostra uma instalação nova
5a instalação corre/tmp/auto_installer.log, /tmp/install-low-level-start-session.log
6ainda no instalador, o webhook responde através do Caddy, depois a máquina reinicia33a instalação passa a Finished com discos, NIC e chaves SSH do host associados

Numa falha, o instalador cai para uma shell, a não ser que a resposta defina Reboot on Error, por isso deixa isso desligado enquanto testas.

SintomaCausa provável
Could not find search domain in resolv.conf.o DHCP não enviou domínio
uma consulta TXT para um nome com um espaçomais de um domínio de pesquisa
Got empty response.registo em falta, zona errada, ou a opção 6 aponta para outro servidor DNS
um URL com um espaço no meiovalor TXT dividido em várias strings
o log diz que o URL veio do DHCPa opção 250 está na rede algures
erro TLS no POSTa impressão digital no DNS não é a do certificado atual do Caddy
ligação fechada sem respostao Caddy abortou-a: sub-rede errada, sem catch token, ou uma rota que não é uma das duas
400 no answer file foundo token funcionou; nenhum filtro correspondeu e não há resposta por omissão nesse token
a resposta erradafiltros sobrepostos; ganha o primeiro do ficheiro
o estado fica em cursoo URL base do webhook ainda aponta para a 8443
o iPXE recarrega-se para sempreo servidor DHCP não está a distinguir o iPXE do firmware
timeout TFTP PXE-E32next-server errado, ou UDP 69 bloqueado

Acrescentar o Proxmox Backup Server

Nada no caminho é específico do Proxmox VE. Constrói um segundo conjunto de ficheiros de arranque a partir da ISO do PBS 4 com o mesmo catch token, em /srv/www/pbs-4/, e acrescenta uma resposta PBS por site com o filtro /product/product=pbs, autorizada no token desse site. Os registos DNS, o Caddy, os tokens e a firewall não mudam.

Para um site com os dois, alguma coisa tem de decidir que produto uma máquina recebe, e um menu é a coisa errada para o decidir. O choose do iPXE sem --timeout fica à espera na consola de que se carregue numa tecla para sempre, o que é o contrário de não assistido.

Deixa a reserva DHCP decidir. Já reservas todos os nós por endereço MAC, por isso marca os PBS e envia a cada marca o seu próprio boot.ipxe:

# /etc/dnsmasq.d/pxe.conf, replacing the single iPXE dhcp-boot line
dhcp-host=aa:bb:cc:dd:ee:01,10.10.50.21,pve01
dhcp-host=aa:bb:cc:dd:ee:31,set:pbs,10.10.50.31,pbs01

dhcp-boot=tag:ipxe,tag:!pbs,http://pdm.example.doc/pve-9.2/boot.ipxe
dhcp-boot=tag:ipxe,tag:pbs,http://pdm.example.doc/pbs-4/boot.ipxe

set:pbs numa reserva marca essa máquina31, e tag:!pbs mantém as duas linhas de arranque mutuamente exclusivas, por isso não há dúvida sobre qual ganha. O boot.ipxe de cada produto já arranca a sua entrada automática ao fim de dez segundos sem ninguém ao teclado15.

Estas linhas passam o dnsmasq --test na 2.91, a versão do meu laboratório, e seguem a sintaxe documentada de dhcp-host e das tags. Ainda não arranquei por PXE um nó PBS através delas, por isso experimenta uma máquina marcada antes de contares com isso.

A partir daí é o mesmo caminho que o Proxmox VE. O instalador do PBS envia "product": "pbs", o Caddy troca para o token do site, e o PDM escolhe a resposta PBS desse site. Nada é escolhido à mão em momento nenhum, e o produto em que um nó se torna fica escrito num só sítio, a reserva, ao lado do seu endereço.

O que decideOnde vive
que ISO arrancaa tag set:pbs na reserva DHCP
que respostas de que site se aplicama sub-rede de origem, através da troca de token do Caddy
que resposta dentro desse siteo filtro /product/product=pbs no PDM

O instalador instala apenas o sistema operativo. O datastore, em armazenamento separado do disco do sistema, é mais um trabalho para o que quer que acabe o nó, o que nos traz de volta ao hook de primeiro arranque em falta.

O que falta decidir

Nada disto te impede de usar este desenho. Cada ponto precisa de alguém que fique responsável por ele.

CompromissoPorque importaO que fazer
o endereço de origem é o portãoqualquer coisa numa VLAN de provisionamento, ou capaz de falsificar um endereço nela, pode ir buscar a resposta desse site: hash da password de root, chaves SSH, chave de subscriçãoisolar a VLAN, port security, só reservas, validade dos tokens, desativar tokens entre implementações
o catch token não é segredoestá em todas as imagens e nesta páginasó filtra pedidos perdidos; a sub-rede e o token real guardado no Caddy é que são o portão
o Caddy consegue ler a chave do PDMservir o certificado do PDM significa que o proxy lê essa chave privadauma ACL só em api.pem e api.key, nada mais do PDM legível, o host bem fechado; a chave nunca sai dele
o DNS é de confiançaum registo TXT forjado manda o instalador para outro lado, e se a impressão digital também vier do DNS o falsificador controla as duasprotege o DNS de provisionamento, ou embute a impressão digital do PDM com --cert-fingerprint e reconstrói quando mudar
os ficheiros de arranque vão por HTTP simplespodem ser lidos ou trocados no fiomantém a rede isolada; iPXE por HTTPS se a tua build o suportar
o token do webhook16 bytes aleatórios, uso único, apagado depois da resposta, mas sem limite de tempo4limpa os registos de instalação antigos
a chave de subscriçãoativada uma vez depois de a rede subir; em caso de falha a chave é apagada e a unidade falha, sem nova tentativa34verifica systemctl --failed nos nós novos
o PDM é um ponto únicohoje não tem alta disponibilidadeuma falha trava instalações novas, não clusters em funcionamento
uma NIC de gestãoa resposta não tem opções de bond, VLAN ou bridge9isso é trabalho pós-instalação, com o mesmo problema do primeiro arranque

Uma primeira versão, construída como deve ser

Esta é uma primeira versão da funcionalidade, e para uma primeira versão é boa. O formulário de resposta é sensato, as regras de seleção são claras depois de as leres, o webhook funciona, e o código é aberto, que é a única razão pela qual tudo o que está acima pôde ser provado em vez de adivinhado. A série de patches passou por quatro rondas na mailing list pública antes de entrar35, e nota-se.

As lacunas são as duas coisas que transformam um servidor de instalação num sistema de provisionamento. Um site é a unidade em que um MSP pensa, e o instalador está em cima dele quando pergunta. Um hook de primeiro arranque é a diferença entre um nó instalado e um nó acabado. Ambos já estão a meio caminho: o instalador tem o hook e o PDM tem o token. Espero que ambos cheguem, e quando chegarem, o Caddy no meio deste desenho fica mais simples em vez de desaparecer, porque um proxy que mantém os segredos do PDM fora de alcance e a 8443 fora da rede vale a pena ter de qualquer maneira.

A razão para o fazer assim entretanto é a que está no início. Dez servidores PXE são dez coisas a ficar desatualizadas a dez velocidades diferentes, e cada uma só é olhada quando falha no dia em que precisas dela. Um parque, mantido atualizado uma vez, com o site deduzido pela rede e os segredos guardados num só sítio, é menos coisa para gerir. Menos coisa para gerir é menos coisa para correr mal, e isso é a maior parte do trabalho.


  1. Proxmox — Proxmox Datacenter Manager 1.1 press release — instalações automáticas, com um novo separador em Remotes que acompanha o progresso das instalações. ↩︎

  2. Proxmox Datacenter Manager documentation — Automated Installations — respostas preparadas, filtros de alvo, templates e «a dedicated token mechanism, separate from the normal API tokens». ↩︎ ↩︎

  3. proxmox-datacenter-manager, lib/pdm-api-types/src/auto_installer.rs — as chaves dos filtros de alvo «are JSON Pointers as per [RFC6901], the values globs»; só uma resposta por omissão. ↩︎

  4. proxmox-datacenter-manager, server/src/api/auto_installer/mod.rs — verificação do token antes da resposta por omissão, primeira correspondência pela ordem do ficheiro, first_boot: None, incrementos do contador, o token de post-hook de uso único, as duas rotas acessíveis sem login no PDM, e os privilégios Sys.Audit/Sys.Modify em /system/auto-installation. ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎

  5. Proxmox VE Roadmap — Proxmox VE 9.2 — preparação para PXE e iPXE, «at least 6 GiB of available memory on the host», e o problema conhecido com megaraid_sas e NVMe em JBOD. ↩︎ ↩︎ ↩︎

  6. Proxmox Bugzilla 8078 — «prepared answer disk setup does not allow to specify multiple udev filters with same name», aberto a 26 de setembro de 2026, estado NEW a 7 de novembro de 2026. ↩︎

  7. Proxmox Bugzilla 7699 — «Add on-first-boot parameter to the PDM remote installation», aberto a 12 de junho de 2026, estado NEW a 7 de novembro de 2026. ↩︎ ↩︎

  8. proxmox, proxmox-installer-types/src/lib.rs — SystemInfo: produto, ISO, DMI e interfaces de rede. ↩︎

  9. Proxmox VE wiki — Automated Installation — as opções [first-boot] e [network], a informação de sistema enviada, e que o token de autenticação «is stored in plain text inside the prepared ISO». ↩︎ ↩︎ ↩︎ ↩︎

  10. Proxmox Bugzilla 8263 — «[Feature Request] auto-installer: client source IP (or X-Forwarded-For) for answer selection and templating», aberto a 31 de outubro de 2026, estado NEW a 7 de novembro de 2026. ↩︎

  11. proxmox-datacenter-manager, debian/changelog — 1.1.1: «match prepared answers in the configuration’s stable order and let the first match win». ↩︎

  12. proxmox, proxmox-installer-types/src/answer.rs — AutoInstallerConfig leva first_boot: Option<FirstBootHookInfo>. ↩︎

  13. pve-installer, proxmox-auto-installer/src/bin/proxmox-auto-installer.rs — o executável de primeiro arranque só é configurado quando a resposta tem uma secção first_boot. ↩︎

  14. pve-installer, proxmox-fetch-answer/src/fetch_plugins/http.rs — primeiro o URL da ISO, depois DHCP, depois DNS; os nomes TXT; a leitura do resolv.conf; dig txt +short sem aspas; o cabeçalho Bearer. ↩︎ ↩︎

  15. pve-installer, proxmox-auto-install-assistant/src/main.rs — --pxe-loader implica --pxe, o diretório de saída, o initrd em gzip, /boot removido da ISO, e o boot.ipxe gerado. ↩︎ ↩︎ ↩︎

  16. proxmox-datacenter-manager, server/src/bin/proxmox-datacenter-api/main.rs — PDM_LISTEN_ADDR é o endereço IPv6 não especificado na PDM_PORT, 8443, fixado na compilação. ↩︎

  17. Caddy releases — a 2.11.1 corrigiu a CVE-2026-27587, um bypass do path matcher através de sequências de escape. ↩︎

  18. Debian sources — caddy — 2.6.2-12+deb13u1 no trixie, 2.11.2-1~bpo13+1 no trixie-backports. ↩︎

  19. Caddy — request_header — «With no prefix, the field is set (overwritten).» ↩︎

  20. Caddy — Request matchers — remote_ip é o par imediato; as comparações de caminho ignoram maiúsculas, são descodificadas de URL, limpas, com barras repetidas juntas. ↩︎ ↩︎

  21. Caddy — handle — «only the first matching handle block will be evaluated». ↩︎

  22. Caddy — Global options — admin usa por omissão localhost:2019; protocols usa por omissão h1 h2 h3. ↩︎ ↩︎

  23. Caddy — file_server — o hide não deve ser tratado como uma fronteira de segurança. ↩︎

  24. Caddy — log — Cookie, Set-Cookie, Authorization e Proxy-Authorization são registados como REDACTED. ↩︎

  25. systemd.service — ExecCondition= — com um código de saída de 1 a 254 «the remaining commands are skipped and the unit is not marked as failed». ↩︎

  26. systemd.path — PathChanged= — «activated if the file which was open for writing gets closed». ↩︎

  27. caddyserver/dist, init/caddy.service — ExecStart=/usr/bin/caddy run --environ --config /etc/caddy/Caddyfile. ↩︎ ↩︎

  28. Caddy — Command line — --environ imprime o ambiente antes de arrancar. ↩︎

  29. Caddy — Caddyfile concepts, environment variables — {$NAME} é substituído antes de o Caddyfile ser analisado. ↩︎

  30. caddyserver/caddy, replacer.go — qualquer chave começada por env. é passada a os.Getenv. ↩︎

  31. dnsmasq manual page — dhcp-match, dhcp-boot, dhcp-host com set:<tag>, enable-tftp, tftp-secure, tftp-mtu, tftp-no-blocksize e gamas static. ↩︎ ↩︎ ↩︎

  32. iPXE — Configuring ISC dhcpd — if exists user-class and option user-class = "iPXE" dá ao iPXE o script e ao firmware o loader. ↩︎

  33. pve-installer, unconfigured.sh — o proxmox-post-hook corre logo depois de o proxmox-auto-installer ter sucesso, antes do reinício. ↩︎

  34. pve-installer, proxmox-first-boot/proxmox-first-boot-subscription — «always drop the staged key, regardless of whether activation succeeded». ↩︎

  35. pdm-devel — “add auto-installer integration”, v4, 40 patches — a série que acrescentou a funcionalidade, com as notas de alteração da v3 para a v4. ↩︎