Ativar ou desativar a firewall

Diferido Assíncrono · 202

PUT /api/v1/servers/{vmid}/firewall

operationIdputServerFirewall

Nível exigido: Operação para ativar, Completo para desativar
Quota: mutação, 300 chamadas por hora

Ativa ou desativa a filtragem no VPS e, em seguida, atualiza as suas regras.

A ativação incide sobre as regras dos conjuntos aplicados ao VPS: uma vez ativa a firewall, todo o tráfego de entrada que não seja autorizado por nenhum deles é bloqueado, tanto em IPv4 como em IPv6. Sem nenhum conjunto aplicado, não tem efeito e enabled mantém-se false: aplique primeiro um conjunto (POST /servers/{vmid}/firewall/sets/{id}).

O nível exigido depende do sentido da alteração: ativar (enabled: true) protege, basta uma chave Operação; desativar (enabled: false) expõe a máquina, é necessária uma chave Completo.

O array tasks pode estar vazio se a tarefa de sincronização ainda não estiver visível no momento da resposta: o estado pode então ser relido com GET /servers/{vmid}/firewall.

Este pedido é processado em segundo plano: responde de imediato enquanto o trabalho continua. Acompanhe-o com os endpoints de tarefas ou pedidos.

Parâmetros do caminho

vmid string obrigatório: Identificador do VPS. Tem de pertencer à conta e ao âmbito da chave.

padrão ^\d+$ Exemplo: 116807

Corpo do pedido

application/json

enabled boolean

true: ativar a filtragem; false: desativá-la

obrigatório

Exemplo de pedido

{
  "enabled": true
}

Respostas

202

Pedido aceite e colocado em fila. Acompanhe a tarefa devolvida com GET /tasks/{id}.

O pedido foi aceite, não executado. A resposta contém uma tarefa a acompanhar.

{
  "data": {
    "tasks": [
      {
        "id": "tsk_000002e1",
        "status": "pending",
        "action": "firewall.sync",
        "vmid": "116807",
        "description": "Mise à jour des règles Firewall pour la VM : 116807",
        "created_at": "2026-08-20T14:31:02+02:00",
        "finished_at": null
      }
    ]
  }
}

Campos da resposta 9

data object
tasks object[]

Tarefas criadas; sempre um array
id string

Identificador opaco

Exemplo: tsk_000002e1
status string

unknown assinalaria um estado que a API não sabe identificar

um de: pending, succeeded, failed, unknown
action string

Tipo de tarefa

um de: server.start, server.stop, server.shutdown, server.reboot, server.reset, server.rebuild, server.enable_rescue, server.disable_rescue, server.reboot_rescue, snapshot.create, snapshot.delete, snapshot.rollback, backup.create, backup.restore, iso.mount, iso.unmount, firewall.sync, firewall.unblock_port_25 TaskAction
vmid string
description string
created_at string (date-time)
finished_at string (date-time)

null enquanto a tarefa estiver em execução

400

Parâmetros inválidos: validation_failed — enabled ausente ou não booleano.

{
  "type": "https://docs.lws.fr/kvm/errors/validation-failed",
  "title": "Paramètres invalides",
  "status": 400,
  "code": "validation_failed",
  "detail": "Paramètre « enabled » invalide.",
  "request_id": "3f9a1c07b2e45d18",
  "errors": {
    "enabled": "Booléen attendu : true pour activer le pare-feu, false pour le désactiver."
  }
}

Campos da resposta 18

type string (uri)

Exemplo: https://docs.lws.fr/kvm/errors/vm-not-found

obrigatório
title string

Título curto

Exemplo: VPS introuvable

obrigatório
status integer (int64)

Estado HTTP

Exemplo: 404

obrigatório
code string

Código de máquina estável (ver «Erros» em Primeiros passos)

Exemplo: vm_not_found

obrigatório
detail string

Mensagem detalhada

Exemplo: Aucun VPS 999999 sur ce compte.

obrigatório
request_id string

Identificador do pedido, a comunicar ao suporte

Exemplo: 3f9a1c07b2e45d18

obrigatório
errors object

validation_failed: mensagem por parâmetro incorreto
required_level string

insufficient_scope: nível exigido pela operação

um de: read, exploitation, full
task_id string

task_already_running: tarefa em curso neste VPS

Exemplo: tsk_000002d5
family string

rate_limited: família de quota esgotada

um de: read, mutation, heavy
limit integer (int64)

rate_limited: limite horário da família
retry_after integer (int64)

rate_limited: segundos a aguardar
lock string

server_locked: bloqueio aplicado pelo hipervisor (backup, snapshot, suspended…)

Exemplo: snapshot
reason string

server_locked: operation_in_progress, há uma operação em curso, tente novamente após Retry-After; suspended, o VPS está em hibernação, inicie-o primeiro; support_notified, bloqueio anómalo, a equipa LWS foi avisada e está a intervir

um de: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: natureza da intervenção, início e fim previsto (null para um incidente)
kind string

um de: works, incident
started_at string (date-time)
expected_end string (date-time)

401

Autenticação recusada: invalid_token — cabeçalho Authorization ausente ou mal formado, ou chave desconhecida; access_disabled — acesso à API cortado para esta conta, ou serviço de API momentaneamente suspenso pela LWS.

cabeçalho Authorization ausente ou mal formado, ou chave desconhecida

{
  "type": "https://docs.lws.fr/kvm/errors/invalid-token",
  "title": "Authentification invalide",
  "status": 401,
  "code": "invalid_token",
  "detail": "Clé inconnue ou révoquée.",
  "request_id": "3f9a1c07b2e45d18"
}

acesso à API cortado para esta conta, ou serviço de API momentaneamente suspenso pela LWS

{
  "type": "https://docs.lws.fr/kvm/errors/access-disabled",
  "title": "Accès API désactivé",
  "status": 401,
  "code": "access_disabled",
  "detail": "L'accès API est désactivé pour ce compte. Réactivez-le depuis la page « API / MCP » du panel.",
  "request_id": "3f9a1c07b2e45d18"
}

Campos da resposta 18

type string (uri)

Exemplo: https://docs.lws.fr/kvm/errors/vm-not-found

obrigatório
title string

Título curto

Exemplo: VPS introuvable

obrigatório
status integer (int64)

Estado HTTP

Exemplo: 404

obrigatório
code string

Código de máquina estável (ver «Erros» em Primeiros passos)

Exemplo: vm_not_found

obrigatório
detail string

Mensagem detalhada

Exemplo: Aucun VPS 999999 sur ce compte.

obrigatório
request_id string

Identificador do pedido, a comunicar ao suporte

Exemplo: 3f9a1c07b2e45d18

obrigatório
errors object

validation_failed: mensagem por parâmetro incorreto
required_level string

insufficient_scope: nível exigido pela operação

um de: read, exploitation, full
task_id string

task_already_running: tarefa em curso neste VPS

Exemplo: tsk_000002d5
family string

rate_limited: família de quota esgotada

um de: read, mutation, heavy
limit integer (int64)

rate_limited: limite horário da família
retry_after integer (int64)

rate_limited: segundos a aguardar
lock string

server_locked: bloqueio aplicado pelo hipervisor (backup, snapshot, suspended…)

Exemplo: snapshot
reason string

server_locked: operation_in_progress, há uma operação em curso, tente novamente após Retry-After; suspended, o VPS está em hibernação, inicie-o primeiro; support_notified, bloqueio anómalo, a equipa LWS foi avisada e está a intervir

um de: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: natureza da intervenção, início e fim previsto (null para um incidente)
kind string

um de: works, incident
started_at string (date-time)
expected_end string (date-time)

403

Acesso recusado: insufficient_scope — nível da chave insuficiente; ip_not_allowed — endereço de chamada não autorizado.

nível da chave insuficiente

{
  "type": "https://docs.lws.fr/kvm/errors/insufficient-scope",
  "title": "Droits insuffisants",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "Niveau de permission « exploitation » requis.",
  "request_id": "3f9a1c07b2e45d18",
  "required_level": "exploitation"
}

endereço de chamada não autorizado

{
  "type": "https://docs.lws.fr/kvm/errors/ip-not-allowed",
  "title": "Adresse non autorisée",
  "status": 403,
  "code": "ip_not_allowed",
  "detail": "L'adresse 203.0.113.10 ne figure pas parmi les adresses autorisées de ce compte.",
  "request_id": "3f9a1c07b2e45d18"
}

Campos da resposta 18

type string (uri)

Exemplo: https://docs.lws.fr/kvm/errors/vm-not-found

obrigatório
title string

Título curto

Exemplo: VPS introuvable

obrigatório
status integer (int64)

Estado HTTP

Exemplo: 404

obrigatório
code string

Código de máquina estável (ver «Erros» em Primeiros passos)

Exemplo: vm_not_found

obrigatório
detail string

Mensagem detalhada

Exemplo: Aucun VPS 999999 sur ce compte.

obrigatório
request_id string

Identificador do pedido, a comunicar ao suporte

Exemplo: 3f9a1c07b2e45d18

obrigatório
errors object

validation_failed: mensagem por parâmetro incorreto
required_level string

insufficient_scope: nível exigido pela operação

um de: read, exploitation, full
task_id string

task_already_running: tarefa em curso neste VPS

Exemplo: tsk_000002d5
family string

rate_limited: família de quota esgotada

um de: read, mutation, heavy
limit integer (int64)

rate_limited: limite horário da família
retry_after integer (int64)

rate_limited: segundos a aguardar
lock string

server_locked: bloqueio aplicado pelo hipervisor (backup, snapshot, suspended…)

Exemplo: snapshot
reason string

server_locked: operation_in_progress, há uma operação em curso, tente novamente após Retry-After; suspended, o VPS está em hibernação, inicie-o primeiro; support_notified, bloqueio anómalo, a equipa LWS foi avisada e está a intervir

um de: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: natureza da intervenção, início e fim previsto (null para um incidente)
kind string

um de: works, incident
started_at string (date-time)
expected_end string (date-time)

404

Recurso não encontrado: vm_not_found — VPS inexistente ou fora do âmbito da chave.

{
  "type": "https://docs.lws.fr/kvm/errors/vm-not-found",
  "title": "VPS introuvable",
  "status": 404,
  "code": "vm_not_found",
  "detail": "Aucun VPS 999999 sur ce compte.",
  "request_id": "3f9a1c07b2e45d18"
}

Campos da resposta 18

type string (uri)

Exemplo: https://docs.lws.fr/kvm/errors/vm-not-found

obrigatório
title string

Título curto

Exemplo: VPS introuvable

obrigatório
status integer (int64)

Estado HTTP

Exemplo: 404

obrigatório
code string

Código de máquina estável (ver «Erros» em Primeiros passos)

Exemplo: vm_not_found

obrigatório
detail string

Mensagem detalhada

Exemplo: Aucun VPS 999999 sur ce compte.

obrigatório
request_id string

Identificador do pedido, a comunicar ao suporte

Exemplo: 3f9a1c07b2e45d18

obrigatório
errors object

validation_failed: mensagem por parâmetro incorreto
required_level string

insufficient_scope: nível exigido pela operação

um de: read, exploitation, full
task_id string

task_already_running: tarefa em curso neste VPS

Exemplo: tsk_000002d5
family string

rate_limited: família de quota esgotada

um de: read, mutation, heavy
limit integer (int64)

rate_limited: limite horário da família
retry_after integer (int64)

rate_limited: segundos a aguardar
lock string

server_locked: bloqueio aplicado pelo hipervisor (backup, snapshot, suspended…)

Exemplo: snapshot
reason string

server_locked: operation_in_progress, há uma operação em curso, tente novamente após Retry-After; suspended, o VPS está em hibernação, inicie-o primeiro; support_notified, bloqueio anómalo, a equipa LWS foi avisada e está a intervir

um de: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: natureza da intervenção, início e fim previsto (null para um incidente)
kind string

um de: works, incident
started_at string (date-time)
expected_end string (date-time)

409

Conflito com o estado atual: task_already_running — já está em curso uma sincronização da firewall ou uma reinstalação; service_suspended — VPS desativado ou expirado: apenas as leituras continuam possíveis.

já está em curso uma sincronização da firewall ou uma reinstalação

{
  "type": "https://docs.lws.fr/kvm/errors/task-already-running",
  "title": "Opération déjà en cours",
  "status": 409,
  "code": "task_already_running",
  "detail": "Une synchronisation du pare-feu est déjà en cours sur ce VPS. Attendez qu'elle aboutisse.",
  "request_id": "3f9a1c07b2e45d18",
  "task_id": "tsk_000002d5"
}

VPS desativado ou expirado: apenas as leituras continuam possíveis

{
  "type": "https://docs.lws.fr/kvm/errors/service-suspended",
  "title": "Service suspendu",
  "status": 409,
  "code": "service_suspended",
  "detail": "Le VPS 116807 est expiré.",
  "request_id": "3f9a1c07b2e45d18"
}

Campos da resposta 18

type string (uri)

Exemplo: https://docs.lws.fr/kvm/errors/vm-not-found

obrigatório
title string

Título curto

Exemplo: VPS introuvable

obrigatório
status integer (int64)

Estado HTTP

Exemplo: 404

obrigatório
code string

Código de máquina estável (ver «Erros» em Primeiros passos)

Exemplo: vm_not_found

obrigatório
detail string

Mensagem detalhada

Exemplo: Aucun VPS 999999 sur ce compte.

obrigatório
request_id string

Identificador do pedido, a comunicar ao suporte

Exemplo: 3f9a1c07b2e45d18

obrigatório
errors object

validation_failed: mensagem por parâmetro incorreto
required_level string

insufficient_scope: nível exigido pela operação

um de: read, exploitation, full
task_id string

task_already_running: tarefa em curso neste VPS

Exemplo: tsk_000002d5
family string

rate_limited: família de quota esgotada

um de: read, mutation, heavy
limit integer (int64)

rate_limited: limite horário da família
retry_after integer (int64)

rate_limited: segundos a aguardar
lock string

server_locked: bloqueio aplicado pelo hipervisor (backup, snapshot, suspended…)

Exemplo: snapshot
reason string

server_locked: operation_in_progress, há uma operação em curso, tente novamente após Retry-After; suspended, o VPS está em hibernação, inicie-o primeiro; support_notified, bloqueio anómalo, a equipa LWS foi avisada e está a intervir

um de: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: natureza da intervenção, início e fim previsto (null para um incidente)
kind string

um de: works, incident
started_at string (date-time)
expected_end string (date-time)

429

Quota excedida: rate_limited — quota horária da família esgotada.

{
  "type": "https://docs.lws.fr/kvm/errors/rate-limited",
  "title": "Quota dépassé",
  "status": 429,
  "code": "rate_limited",
  "detail": "Quota dépassé pour les opérations de type « mutation » : 300 appels par heure. Réessayez dans 95 seconde(s).",
  "request_id": "3f9a1c07b2e45d18",
  "family": "mutation",
  "limit": 300,
  "retry_after": 95
}

Campos da resposta 18

type string (uri)

Exemplo: https://docs.lws.fr/kvm/errors/vm-not-found

obrigatório
title string

Título curto

Exemplo: VPS introuvable

obrigatório
status integer (int64)

Estado HTTP

Exemplo: 404

obrigatório
code string

Código de máquina estável (ver «Erros» em Primeiros passos)

Exemplo: vm_not_found

obrigatório
detail string

Mensagem detalhada

Exemplo: Aucun VPS 999999 sur ce compte.

obrigatório
request_id string

Identificador do pedido, a comunicar ao suporte

Exemplo: 3f9a1c07b2e45d18

obrigatório
errors object

validation_failed: mensagem por parâmetro incorreto
required_level string

insufficient_scope: nível exigido pela operação

um de: read, exploitation, full
task_id string

task_already_running: tarefa em curso neste VPS

Exemplo: tsk_000002d5
family string

rate_limited: família de quota esgotada

um de: read, mutation, heavy
limit integer (int64)

rate_limited: limite horário da família
retry_after integer (int64)

rate_limited: segundos a aguardar
lock string

server_locked: bloqueio aplicado pelo hipervisor (backup, snapshot, suspended…)

Exemplo: snapshot
reason string

server_locked: operation_in_progress, há uma operação em curso, tente novamente após Retry-After; suspended, o VPS está em hibernação, inicie-o primeiro; support_notified, bloqueio anómalo, a equipa LWS foi avisada e está a intervir

um de: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: natureza da intervenção, início e fim previsto (null para um incidente)
kind string

um de: works, incident
started_at string (date-time)
expected_end string (date-time)

502

Dependência inacessível: hypervisor_unreachable — base de dados do hipervisor sem resposta, nada foi modificado; upstream_unavailable — inventário dos VPS momentaneamente indisponível.

base de dados do hipervisor sem resposta, nada foi modificado

{
  "type": "https://docs.lws.fr/kvm/errors/hypervisor-unreachable",
  "title": "Hyperviseur injoignable",
  "status": 502,
  "code": "hypervisor_unreachable",
  "detail": "La base de l'hyperviseur n'a pas répondu, le pare-feu n'a pas été modifié.",
  "request_id": "3f9a1c07b2e45d18"
}

inventário dos VPS momentaneamente indisponível

{
  "type": "https://docs.lws.fr/kvm/errors/upstream-unavailable",
  "title": "Service momentanément indisponible",
  "status": 502,
  "code": "upstream_unavailable",
  "detail": "Inventaire des VM indisponible.",
  "request_id": "3f9a1c07b2e45d18"
}

Campos da resposta 18

type string (uri)

Exemplo: https://docs.lws.fr/kvm/errors/vm-not-found

obrigatório
title string

Título curto

Exemplo: VPS introuvable

obrigatório
status integer (int64)

Estado HTTP

Exemplo: 404

obrigatório
code string

Código de máquina estável (ver «Erros» em Primeiros passos)

Exemplo: vm_not_found

obrigatório
detail string

Mensagem detalhada

Exemplo: Aucun VPS 999999 sur ce compte.

obrigatório
request_id string

Identificador do pedido, a comunicar ao suporte

Exemplo: 3f9a1c07b2e45d18

obrigatório
errors object

validation_failed: mensagem por parâmetro incorreto
required_level string

insufficient_scope: nível exigido pela operação

um de: read, exploitation, full
task_id string

task_already_running: tarefa em curso neste VPS

Exemplo: tsk_000002d5
family string

rate_limited: família de quota esgotada

um de: read, mutation, heavy
limit integer (int64)

rate_limited: limite horário da família
retry_after integer (int64)

rate_limited: segundos a aguardar
lock string

server_locked: bloqueio aplicado pelo hipervisor (backup, snapshot, suspended…)

Exemplo: snapshot
reason string

server_locked: operation_in_progress, há uma operação em curso, tente novamente após Retry-After; suspended, o VPS está em hibernação, inicie-o primeiro; support_notified, bloqueio anómalo, a equipa LWS foi avisada e está a intervir

um de: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: natureza da intervenção, início e fim previsto (null para um incidente)
kind string

um de: works, incident
started_at string (date-time)
expected_end string (date-time)

503

Servidor anfitrião em intervenção: server_maintenance — servidor anfitrião em intervenção anunciada pela LWS e inacessível; respeite Retry-After.

{
  "type": "https://docs.lws.fr/kvm/errors/server-maintenance",
  "title": "Intervention en cours sur le serveur hôte",
  "status": 503,
  "code": "server_maintenance",
  "detail": "Le serveur hébergeant ce VPS fait l'objet d'une intervention programmée par LWS : il est momentanément inaccessible. Fin prévue : 2026-10-21T18:00:00+02:00.",
  "request_id": "3f9a1c07b2e45d18",
  "maintenance": {
    "kind": "works",
    "started_at": "2026-10-21T14:00:00+02:00",
    "expected_end": "2026-10-21T18:00:00+02:00"
  }
}

Campos da resposta 18

type string (uri)

Exemplo: https://docs.lws.fr/kvm/errors/vm-not-found

obrigatório
title string

Título curto

Exemplo: VPS introuvable

obrigatório
status integer (int64)

Estado HTTP

Exemplo: 404

obrigatório
code string

Código de máquina estável (ver «Erros» em Primeiros passos)

Exemplo: vm_not_found

obrigatório
detail string

Mensagem detalhada

Exemplo: Aucun VPS 999999 sur ce compte.

obrigatório
request_id string

Identificador do pedido, a comunicar ao suporte

Exemplo: 3f9a1c07b2e45d18

obrigatório
errors object

validation_failed: mensagem por parâmetro incorreto
required_level string

insufficient_scope: nível exigido pela operação

um de: read, exploitation, full
task_id string

task_already_running: tarefa em curso neste VPS

Exemplo: tsk_000002d5
family string

rate_limited: família de quota esgotada

um de: read, mutation, heavy
limit integer (int64)

rate_limited: limite horário da família
retry_after integer (int64)

rate_limited: segundos a aguardar
lock string

server_locked: bloqueio aplicado pelo hipervisor (backup, snapshot, suspended…)

Exemplo: snapshot
reason string

server_locked: operation_in_progress, há uma operação em curso, tente novamente após Retry-After; suspended, o VPS está em hibernação, inicie-o primeiro; support_notified, bloqueio anómalo, a equipa LWS foi avisada e está a intervir

um de: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: natureza da intervenção, início e fim previsto (null para um incidente)
kind string

um de: works, incident
started_at string (date-time)
expected_end string (date-time)

Ativar ou desativar a firewall

Parâmetros do caminho

Corpo do pedido

Respostas

Comunicar um erro

Assistente IA