Vender alojamento web com Virtualmin

O Virtualmin é um dos painéis de controlo mais antigos ainda em uso real (existe desde 2004) e tem uma base instalada que o GitHub não mostra. A 21 de agosto de 2026, o repositório tinha 412 estrelas, 129 forks e 46 colaboradores, o que é pouco para os padrões do GitHub e quase nada diz sobre quantos pequenos alojadores realmente o usam.

O que diz, isso sim, é que muito pouco se escreveu sobre vender com o Virtualmin. Esta página é exatamente isso: como o Provibr se liga a uma máquina Virtualmin, que decisões o painel impõe, e onde estão as arestas vivas. Tudo o que se segue foi medido numa instalação real de Virtualmin GPL 8.1.2 em Ubuntu 24.04.

O Webmin é o painel, o Virtualmin faz o alojamento

O produto é conhecido pelo nome de Webmin. É o nome na página de início de sessão, na documentação e em todas as pesquisas. Mas o Webmin sozinho administra uma máquina Linux: não tem qualquer noção de conta de alojamento. O que o Provibr realmente comanda é o Virtualmin: o módulo que conhece os domínios, os planos e as quotas.

Isto importa mais do que parece. Numa máquina sem esse módulo, o ponto de acesso da API remota do Virtualmin simplesmente não existe: responde exatamente como um nome de módulo inventado. Foi medido na etapa zero do estudo, antes de qualquer instalação. Não há, portanto, recuo para o Webmin sozinho, e o Provibr não finge que há: a ligação é recusada com um motivo em vez de ser criada a meio.

O que é preciso para ligar

Quatro campos, e dois deles mais estritos do que para qualquer outro painel de controlo que suportamos.

Porque https e a impressão digital são ambos obrigatórios. As nossas outras integrações de painéis de controlo aceitam um endereço http simples e dizem o que isso custa. Esta não, e a diferença está na natureza do segredo.

A API remota do Webmin fala HTTP Basic. O segredo aqui é uma palavra-passe, não um token. Isso é uma propriedade do Webmin, não uma escolha nossa. Uma chave de acesso do DirectAdmin pode ser limitada a um punhado de comandos; uma palavra-passe do Webmin não pode ser limitada de todo. Enviá-la sem cifra, ou para um certificado que ninguém verificou, não é um compromisso que façamos em seu nome. E o instalador do Webmin deixa um certificado autoassinado, pelo que o campo da impressão digital não é teórico: é o caso normal.

Conselho prático: crie-se um utilizador Webmin dedicado e dê-se-lhe o módulo Virtualmin. Pode fazer tudo o que o Virtualmin faz, o que já é muito, mas não tudo o que o Webmin faz.

Duas coisas que vão morder uma integração

São os dois comportamentos medidos com maior probabilidade de custar uma tarde a quem construa isto por si próprio.

Todo o erro chega com HTTP 200. O Virtualmin tem duas formas de falha (error ao nível do invólucro e failure ao nível do programa) e entrega ambas com um código de estado 200. O código de estado não diz nada. Tudo o que não seja exatamente status: "success" é uma falha, e o erro de invólucro tem de ser verificado antes de qualquer comparação de texto, caso contrário «Remote program xyz does not exist» lê-se como uma conta em falta.

(Isto é um traço de família das APIs de painéis de controlo, não uma esquisitice do Virtualmin. O DirectAdmin faz o mesmo de outra forma: HTTP 200 com error=1 no corpo. Uma integração que confie no código de estado tem êxito em silêncio quando nada aconteceu.)

Um caminho de interface responde com 200 e uma página de início de sessão. Se se aponta para um caminho de módulo Webmin em vez da API remota, obtém-se um HTTP 200 com uma página HTML de início de sessão, para uma palavra-passe errada, uma correta e nenhuma por igual, as três indistinguíveis pelo código de estado. A própria API remota fá-lo como deve ser, com uma 401. É essa diferença que torna o erro aproveitável: um 200 com HTML só pode significar uma coisa, que não se está a apontar para a API. E o Provibr di-lo pelo nome, em vez de mostrar um erro de análise de JSON num painel que funciona perfeitamente.

Algumas instalações têm a rota da API remota desligada. Volta-se a ligá-la em Webmin → Webmin Configuration → Advanced Options.

Definições: não há nenhuma

Um servidor Virtualmin decide por si onde vive uma conta e que endereço recebe. Não resta nada para configurar, pelo que o separador de definições não traz mais do que a opção de reenviar as credenciais.

Isso inclui o endereço IP. O Virtualmin coloca uma conta no endereço partilhado do anfitrião por predefinição (medimos ip_address a regressar como 192.0.2.10 (Shared)), pelo que a gestão de endereços do Provibr fica desligada para este fornecedor. Um IPAM que desse a entender que estava a atribuir o endereço estaria a mentir.

Os planos

Um plano Virtualmin é a descrição que o próprio painel faz de uma conta: quota de disco, tráfego mensal, quantos domínios e caixas de correio, que funcionalidades estão ativas. Não é um plano Provibr nem um sistema operativo: é um nome ao qual nos referimos, e o seu conteúdo pode mudar no seu servidor sem que o saibamos.

A página de integração lê a lista de planos com o seu conteúdo, para que se veja o que se está a escolher em vez de escrever um nome de memória. Um plano web Provibr fixa então um plano Virtualmin numa integração e dá-lhe um nome próprio. Encomendar através de um plano é melhor do que escolher um solto, e o seletor solto continua disponível para os casos que um plano não cobre.

⚠️ Uma armadilha medida que convém conhecer: modify-domain com um nome de plano que não existe responde status: "success" e deixa o plano exatamente onde estava. Não há forma de erro a classificar: a recusa é o silêncio. O Provibr compara o que pediu com o que relê a seguir, pelo que uma mudança de plano que não aconteceu é comunicada como não tendo acontecido.

Como é uma conta no Provibr

Uma conta de alojamento é uma linha de servidor vulgar do tipo webserver. Criar uma exige um domínio, um endereço de e-mail, um plano e uma palavra-passe.

• O identificador é o número interno que o Virtualmin dá ao domínio, não o nome. O Virtualmin pode renomear um domínio; uma chave baseada no nome soltar-se-ia da sua linha na primeira vez que alguém o fizesse.
• O utilizador unix é derivado do domínio, por isso my-client.nl torna-se my-client. Os hífenes são aqui a forma normal, não a exceção, e o limite é o próprio do Linux, 32 caracteres. Isso é diferente do DirectAdmin e do cPanel, que impõem as suas próprias regras de nomenclatura mais estritas.
• A fronteira da conta é o utilizador unix, não o domínio. Caso contrário, os subservidores e os aliases cairiam cada um na contagem de licença como contas de alojamento distintas.
• A palavra-passe não é registada em lado nenhum. Só o facto de se ter fornecido uma o é; o valor viaja em separado e nunca é escrito numa linha de auditoria.
• A seguir, é possível suspender, reativar, mudar de plano e eliminar. Não há consola: uma conta de alojamento não tem nenhuma.

Suspenso significa que existe um campo

Este é o pormenor mais fino de toda a integração, e é precisamente o que um analisador feito à mão erra.

Numa conta suspensa, list-domains ganha um campo chamado disabled. Numa conta ativa, esse campo está simplesmente ausente. Não existe um disabled: "No".

Um analisador que procura um valor nunca encontra nenhum, e lê todas as contas como ativas, incluindo as suspensas. Num contexto de faturação, isso não é um defeito cosmético: significa que uma conta suspensa por falta de pagamento se declara ativa, e a contagem de capacidade fica errada no sentido que custa dinheiro.

Quota e utilização: por vezes não há nada para mostrar

A quota de disco e o tráfego viajam com a sondagem habitual, pelo que uma conta obtém um gráfico de utilização sem que seja preciso ligar nada de extra, desde que o servidor os consiga medir.

O Virtualmin só comunica quota e utilização quando as quotas do sistema de ficheiros estão ligadas, e uma instalação nova tem-nas desligadas. Medimo-lo: quotaon -p / respondeu off numa instalação de origem, porque o instalador escreve o antigo formato de quota em /etc/fstab enquanto um núcleo ext4 moderno quer quotas journaled. Até alguém as ligar, não aparece qualquer campo de quota na saída da API.

O Provibr não mostra nada, em vez de um zero. Ausência de medição e ausência de utilização não são a mesma coisa, e um gráfico fixado em zero parece a segunda quando é a primeira.

Uma nota relacionada para quem alguma vez leia a saída em bruto por si próprio: prefiram-se os campos legíveis por máquina (created_unix_time, databases_byte_size) aos seus gémeos humanos (created_on, databases_size). Os humanos trazem unidades e um formato de data que dependem da língua do painel, e analisá-los é exatamente o tipo de falha silenciosa que se manifesta primeiro num cliente com uma definição diferente.

Duas omissões deliberadas

O teste de ligação não mostra uma linha de versão. O Virtualmin não tem qualquer programa de API que devolva a sua própria versão: virtualmin info conhece vinte e uma chaves de pesquisa e nenhuma é uma versão, e o cabeçalho Server: MiniServ não traz número. Uma linha vazia daria a entender que tentámos e não conseguimos lê-la; omiti-la diz a verdade. O teste mostra, em vez disso, a lista de planos, que é o que realmente se quer confirmar.

E nada de secreto do painel é alguma vez guardado. list-domains --multiline transporta hashed_password, password_for_mysql e password_storage literalmente na sua saída. O Provibr filtra com uma lista de permissões antes de ler, não por ocultação a posteriori: uma lista de negação falha o próximo segredo que receba outro nome. Verificámo-lo com uma contraprova na mesma execução: a resposta em bruto do painel transporta de facto esses três campos, e a lista de importação não contém nenhum deles.

Adotar contas que já existem

O separador de importação lista as contas presentes no painel e permite trazer para o Provibr aquelas que se quiser. As contas já conhecidas são mostradas mas não podem ser selecionadas de novo, para que se veja a imagem inteira e não uma filtrada.

As contas importadas contam para a capacidade exatamente como as contas encomendadas. Importe-se mais do que aquilo para que há espaço e abre-se um excedente, com o período de tolerância habitual.

O que isto significa para um pequeno alojador

O Virtualmin é um bom painel com quase nenhuma ferramenta comercial à sua volta. O conselho habitual (mudar para algo que os sistemas de faturação já falem) pede que se migrem clientes em produção de uma máquina que funciona, para resolver um problema burocrático.

O Provibr liga-se a painéis de controlo, hipervisores e painéis de jogo lado a lado. Mantenha-se a máquina Virtualmin que já se tem, coloque-se por cima a encomenda e a contagem de capacidade, e acrescente-se ao lado um VPS ou um painel de jogos mais tarde, sem mudar nada no funcionamento do lado do alojamento.