Blog

Whitepaper técnico — PodHeitor Firebird para Bacula

Whitepaper técnico — PodHeitor Firebird para Bacula

Whitepaper Técnico — Versão 0.1.0 — Maio de 2026

Autor: Heitor Faria · Website: https://podheitor.com · Email: heitor@opentechs.lat · Telefone / WhatsApp: +1 786 726-1749 | +55 61 98268-4220

Oferta especial. Traga sua proposta de renovação de qualquer plataforma comercial de backup empresarial — Veeam, Commvault, NetBackup ou outras. Elaboraremos uma proposta comparativa visando economia mínima de 50% com funcionalidade superior e específica para Firebird. Contato: heitor@opentechs.lat para uma proposta formal por escrito.

Sumário

  1. Resumo executivo
  2. Introdução e contexto de mercado
  3. Visão geral da arquitetura
  4. Modos de backup em detalhes
  5. Matriz de funcionalidades
  6. Guia de instalação
  7. Referência de configuração
  8. Exemplos de FileSet
  9. Dimensionamento e planejamento de capacidade
  10. Relatório de desempenho
  11. Matriz de compatibilidade
  12. Segurança
  13. Monitoramento
  14. Guia de solução de problemas
  15. Casos de uso e cenários de implantação
  16. Comparação com outras abordagens
  17. Roadmap
  18. Conclusão
  19. Informações de contato
  20. Legal / direitos autorais

1. Resumo executivo

O Firebird é um banco de dados relacional open-source maduro, amplamente implantado em sistemas ERP, aplicações de ponto de venda, produtos embarcados e aplicações empresariais — com adoção especialmente intensa na América Latina, Europa Oriental e Ásia. Apesar dessa presença, o Firebird historicamente nunca contou com uma integração de backup de primeira classe com o ecossistema de backup open-source. Os administradores eram forçados a escolher entre scripts shell artesanais que invocam o gbak, plugins pagos de fornecedores comerciais, ou simplesmente aceitar falhas silenciosas de backup sem nenhuma camada de verificação.

O PodHeitor Firebird Backup Plugin for Bacula fecha essa lacuna. Ele entrega um plugin production-grade nativo em Rust para Bacula Community 15.0.3+, integrado nativamente ao Firebird 3.0, 4.0 e 5.0. Três modos distintos de backup cobrem todos os cenários operacionais: dump lógico via gbak com modo dump, cadeias incrementais page-level nativas via nbackup, e log shipping com o modo replay para replicação com RPO próximo de zero. Todos os modos são gerenciados pela configuração padrão de Job e FileSet do Bacula — sem scripts externos, sem cron como cola, sem daemons customizados.

Do ponto de vista de negócios, o plugin estende o Bacula Community com capacidades de DR para Firebird em nível enterprise, a uma fração do custo das alternativas comerciais premium. Testes de validação em 8 fases e 120 casos de teste automatizados confirmaram restauração byte a byte idêntica, throughput paralelo multi-DB (aceleração de 5,6×), compressão zstd (razão on-wire de 21,4%) e drift de limitação de banda inferior a 1%. Para qualquer organização que executa Firebird no Linux com Bacula Community, este plugin é o caminho mais completo e mais econômico para uma postura de backup sólida e auditável.

2. Introdução e contexto de mercado

2.1 O Firebird em produção hoje

O Firebird continua sendo o banco de dados de escolha para milhões de aplicações instaladas em todo o mundo. Ele sustenta as principais plataformas de ERP na América Latina (Totvs Protheus e similares), sistemas de apólices de seguros, gestão logística e de estoque, e dispositivos industriais embarcados. As características que explicam sua adoção continuada incluem:

  • Licenciamento gratuito, sem taxas por usuário ou por núcleo
  • Autogerenciamento de páginas, sem necessidade de DBA para operação rotineira
  • Versionamento ODS (On-Disk Structure) que viabiliza migrações limpas entre versões principais
  • Arquitetura multigeracional que garante leituras consistentes sem bloqueio de escrita
  • Footprint de memória extremamente reduzido — instâncias Firebird em produção frequentemente operam com menos de 256 MB de RAM

Essas mesmas características que tornam o Firebird atrativo também criam desafios para o backup. O banco de dados não implementa um stream WAL (Write-Ahead Log) consumível por ferramentas genéricas de log shipping. Seu formato em disco varia entre versões ODS (ODS 11 para FB 3, ODS 12 para FB 4, ODS 13 para FB 5). As ferramentas nativas de backup — gbak para dumps lógicos e nbackup para backups page-level — existem e são robustas, mas utilizam protocolos proprietários que nenhuma plataforma de backup open-source havia integrado até agora.

2.2 Por que as abordagens existentes são insuficientes

Ferramenta Suporte ao Firebird Veredicto
Bacula Community (nativo, sem plugin) Somente nível de arquivo — faz backup do arquivo .fdb bruto com o banco ativo Inseguro — risco de corrupção de dados se o banco estiver em uso
Veeam Sem agente Firebird nativo Exige scripts de quiesce no nível do SO; sem verificação pelo motor de backup
Commvault Sem iDataAgent nativo para Firebird Integração apenas via scripts customizados
Amanda / Bareos Somente nível de arquivo Mesmo risco do backup de arquivo nativo do Bacula Community
Scripts shell customizados Não confiáveis, sem retry, sem monitoramento, sem catálogo Não é production-grade

A lacuna é evidente: até agora, nenhuma solução de backup compatível com open-source integrava o Firebird no nível do motor. O plugin PodHeitor preenche essa lacuna.

2.3 A abordagem PodHeitor

O plugin segue a mesma filosofia de design da família de plugins PodHeitor: implementação nativa em Rust, desenvolvimento com fases validadas por testes de regressão automatizados, zero dependências de runtime além das ferramentas do banco de dados alvo, e uma arquitetura de protocolo PTCOMM que torna a divisão cdylib/backend trivialmente segura diante de mudanças na API interna do Bacula.

3. Visão geral da arquitetura

3.1 Design em dois componentes

O plugin é composto por dois binários distribuídos no mesmo pacote:

Componente Arquivo Função
Plugin FD do Bacula (cdylib) /opt/bacula/plugins/podheitor-firebird-fd.so Carregado pelo bacula-fd em runtime; implementa a API de plugins do Bacula
Binário backend /opt/bacula/bin/podheitor-firebird-backend Executado como subprocesso por job pelo cdylib; realiza toda a interação com o Firebird

Essa separação é intencional e oferece três vantagens principais:

  1. Isolamento. O cdylib é mínimo e estável. Toda a lógica que interage com as ferramentas Firebird (gbak, nbackup, gfix, Services API) reside no backend. Um crash ou travamento no backend não pode corromper o processo bacula-fd.
  2. Atualizabilidade. O backend pode ser atualizado sem reiniciar o bacula-fd. Somente o cdylib toca a ABI de plugins do Bacula.
  3. Testabilidade. O binário backend pode ser exercitado diretamente em testes de integração, sem envolver o Bacula.

3.2 Protocolo PTCOMM

O cdylib e o backend se comunicam via stdin/stdout do processo filho usando o PTCOMM (PodHeitor Transport Communications), um protocolo de enquadramento binário com tag de comprimento:

┌────────────────────────────────────────────────────────┐
│  PTCOMM Frame (8-byte header + payload)                │
│                                                        │
│  Offset  Size  Field                                   │
│  ──────  ────  ─────                                   │
│  0       4     Magic  (0x50544300)                     │
│  4       4     Payload length (u32, big-endian)        │
│  8       N     Payload (JSON or binary blob)           │
└────────────────────────────────────────────────────────┘

As mensagens são enums Rust serializados em JSON:

  • BackupRequest { db, mode, level, options... } — cdylib → backend, uma vez por job
  • BackupChunk { seq, data: bytes } — backend → cdylib, em streaming para cada bloco de dados
  • BackupComplete { size, checksum, metadata } — backend → cdylib, fim do stream de backup
  • RestoreRequest { db, restore_path, mode, options... } — cdylib → backend
  • RestoreChunk { seq, data: bytes } — cdylib → backend, dados de restauração em streaming
  • RestoreComplete { rows_verified } — backend → cdylib, fim da restauração
  • ErrorResponse { code, message } — em qualquer direção, em caso de falha

3.3 Diagrama de arquitetura

  ┌─────────────────────────────────────────────────────────────┐
  │  Bacula File Daemon (bacula-fd)                              │
  │                                                             │
  │   ┌─────────────────────────────────────────────────────┐   │
  │   │  podheitor-firebird-fd.so  (cdylib)                  │   │
  │   │                                                     │   │
  │   │  bEventJobStart ──► fork backend ──► write job opts │   │
  │   │  bEventBackupCommand ──► send BackupRequest         │   │
  │   │  bEventGetMoreData ◄── receive BackupChunk          │   │
  │   │  bEventEndBackupJob ──► read BackupComplete         │   │
  │   │  bEventRestoreCommand ──► send RestoreRequest       │   │
  │   │  bEventSetFileAttributes ◄── write restored file    │   │
  │   └───────────────────────┬─────────────────────────────┘   │
  │                           │ stdin/stdout (PTCOMM)            │
  │   ┌───────────────────────▼─────────────────────────────┐   │
  │   │  podheitor-firebird-backend  (subprocess)            │   │
  │   │                                                     │   │
  │   │  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │   │
  │   │  │ DumpMode │  │NbackupMod│  │  ReplayMode      │  │   │
  │   │  │  (gbak)  │  │(nbackup) │  │ (gbak+log ship)  │  │   │
  │   │  └────┬─────┘  └────┬─────┘  └────────┬─────────┘  │   │
  │   │       │              │                  │            │   │
  │   │  ┌────▼──────────────▼──────────────────▼────────┐  │   │
  │   │  │  Firebird Engine (gbak / nbackup / gfix /      │  │   │
  │   │  │  Services API / Embedded)                      │  │   │
  │   │  └────────────────────────────────────────────────┘  │   │
  │   │                                                     │   │
  │   │  State dir: /opt/bacula/working/firebird-state/     │   │
  │   │  Config:    /opt/bacula/etc/podheitor-firebird.conf  │   │
  │   └─────────────────────────────────────────────────────┘   │
  └─────────────────────────────────────────────────────────────┘
                         │
                         │ Bacula protocol (TCP)
                         ▼
               ┌──────────────────┐
               │  Bacula Storage  │
               │  Daemon (bacula- │
               │  sd) + Catalog   │
               └──────────────────┘

3.4 Gerenciamento de estado

O modo nbackup requer estado persistente para rastrear quais níveis da cadeia incremental foram concluídos. Esse estado é armazenado em /opt/bacula/working/firebird-state/ como arquivos de manifesto JSON por banco de dados:

/opt/bacula/working/firebird-state/
  ├── prod.fdb.chain.json          # nbackup chain manifest
  ├── employee.fdb.chain.json
  └── inventory.fdb.chain.json

Cada manifesto registra:

{
  "db_path": "/var/firebird/prod.fdb",
  "chain": [
    { "level": 0, "job_id": 100, "size": 1048576, "checksum": "sha256:...", "timestamp": "2026-05-01T02:00:00Z" },
    { "level": 1, "job_id": 101, "size": 204800,  "checksum": "sha256:...", "timestamp": "2026-05-02T02:00:00Z" }
  ]
}

4. Modos de backup em detalhes

4.1 Modo dump — backup lógico via gbak

Como funciona

O modo dump invoca o utilitário gbak do Firebird para produzir um backup lógico portável. O gbak conecta-se ao servidor Firebird (ou ao motor embarcado), lê todas as páginas de dados em um snapshot consistente e escreve um stream .fbk independente de plataforma. O plugin captura esse stream, opcionalmente o comprime e o envia ao Bacula como um único objeto de arquivo virtual.

  Firebird DB  ──►  gbak  ──►  stdout stream  ──►  (zstd compress)  ──►  PTCOMM chunk stream  ──►  Bacula

Trabalhadores paralelos podem ser especificados (workers=N) para fazer backup de múltiplos bancos de dados simultaneamente em um único job Bacula.

Quando usar

  • Backups completos noturnos de bancos de dados de pequeno a médio porte (< 50 GB sem compressão)
  • Migração entre versões (o formato .fbk do gbak é portável entre as versões ODS do FB 3/4/5)
  • Qualquer cenário que exija consistência lógica em vez de fidelidade de página bruta
  • Recuperação de desastres onde um backup limpo e importável é necessário sem dependências de cadeia

Prós e contras

Aspecto Avaliação
Portabilidade Excelente — o .fbk restaura em qualquer versão do FB
Consistência Excelente — o gbak gera um snapshot consistente
Velocidade Moderado — lê todas as páginas sequencialmente
Tamanho Moderado — dados lógicos; compressão zstd ajuda
Dependência de cadeia Nenhuma — cada backup é autossuficiente
Simplicidade de restauração Excelente — uma única invocação de gbak -r
Adequação a grandes bancos Moderado — o tempo de backup completo cresce linearmente com o tamanho do banco
Suporte a paralelismo Sim — múltiplos bancos em um único job

4.2 Modo nbackup — cadeia incremental page-level nativa

Como funciona

O modo nbackup utiliza a funcionalidade de backup page-level nativa do Firebird. Opera em quatro níveis (L0 a L3):

  • Nível 0 (L0): snapshot completo page-level do banco de dados
  • Nível 1 (L1): páginas alteradas desde o último L0
  • Nível 2 (L2): páginas alteradas desde o último L1
  • Nível 3 (L3): páginas alteradas desde o último L2

O Firebird rastreia internamente as páginas alteradas via mecanismo de arquivo de diferença. O plugin gerencia o manifesto da cadeia, invoca nbackup -b &lt;level&gt; para o nível apropriado e registra o resultado. Na restauração, o plugin mescla a cadeia usando nbackup -r na ordem estrita de níveis (L0 → L1 → L2 → L3).

  Day 1:  nbackup -b 0 ──► L0.nbk  (full page snapshot)
  Day 2:  nbackup -b 1 ──► L1.nbk  (delta from L0)
  Day 3:  nbackup -b 2 ──► L2.nbk  (delta from L1)
  Day 4:  nbackup -b 3 ──► L3.nbk  (delta from L2)
  Day 5:  nbackup -b 0 ──► new L0  (chain resets)

Quando usar

  • Bancos de dados grandes nos quais o gbak completo todas as noites é lento demais ou grande demais
  • Ambientes com janelas de RTO/RPO definidas que se beneficiam de cadeias incrementais
  • Quando o orçamento de disco ou de banda é limitado
  • Quando o banco de dados está no mesmo host ou acessível via Services API

Prós e contras

Aspecto Avaliação
Portabilidade Baixo — específico para ODS; deve restaurar na mesma versão principal do Firebird
Consistência Excelente — o Firebird garante consistência page-level
Velocidade Excelente — L1/L2/L3 faz backup apenas das páginas alteradas
Tamanho Excelente — os deltas incrementais são pequenos
Dependência de cadeia Obrigatório — a restauração requer a cadeia completa L0→Ln
Simplicidade de restauração Moderado — deve restaurar na ordem da cadeia
Adequação a grandes bancos Excelente — a cadeia incremental escala para bancos de dados com múltiplos GB
Suporte a paralelismo Por nível, por banco de dados

4.3 Modo replay — baseline gbak + log shipping de journal

Como funciona

O modo replay implementa uma estratégia em dois níveis:

  1. Baseline. Um dump lógico completo via gbak é realizado periodicamente (configurável).
  2. Segmentos de journal. Arquivos de journal de replicação do Firebird produzidos pelo subsistema de replicação (FB 4+) são coletados de replay_log_dir, enviados ao Bacula e, na restauração, depositados em replay_dest_dir para replay.

Esse padrão espelha a abordagem de log shipping usada na replicação em streaming do PostgreSQL, adaptada ao mecanismo de journal do Firebird.

  Firebird (primary)
    ├── gbak baseline ──────────────────────────────────────────► Bacula catalog
    └── journal segments (repllog.*.journal) ──► PTCOMM stream ──► Bacula catalog

  Restore:
    gbak -r baseline ──► fresh DB ──► apply journal segments ──► consistent standby

Quando usar

  • Requisitos de RPO próximo de zero nos quais as cadeias incrementais do nbackup ainda são muito granulares
  • Cenários de replicação em standby e DR
  • Instalações com Firebird 4.0 e 5.0 com replicação já habilitada
  • DR multi-site onde os journals podem ser aplicados em um standby remoto

Prós e contras

Aspecto Avaliação
RPO Excelente — sub-minuto com envio frequente de journals
Portabilidade Moderado — o baseline é portável; os journals são específicos de versão
Consistência Excelente — os journals são segmentos atômicos
Complexidade de configuração Alto — exige que a replicação do Firebird esteja configurada
Complexidade de restauração Moderado — o replay requer aplicação ordenada dos journals
Adequação a grandes bancos Excelente — os journals são pequenos independentemente do tamanho do banco
Requisito de versão do FB Replicação disponível a partir do FB 4.0

5. Matriz de funcionalidades

Funcionalidade dump nbackup replay
Backup completo Sim Sim (L0) Sim (baseline)
Backup incremental Não Sim (L1/L2/L3) Sim (journals)
Compressão zstd Sim Sim Sim
Compressão lz4 Sim Sim Sim
Limitação de banda Sim Sim Sim
Workers paralelos Sim Não Não
Multi-DB por job Sim Sim Sim
Restauração entre versões Sim Não Parcial
Services API Sim Sim Sim
Firebird Embedded Sim Sim Não
gfix pós-restauração Sim Sim Não
Passphrase de criptografia Sim Sim Sim
Métricas Prometheus Sim Sim Sim
Gerenciamento de estado da cadeia Não Sim Não
CLI gc-chain Não Sim Não
Restauração byte a byte idêntica Sim Sim Sim
Pacote RPM Sim Sim Sim
Pacote DEB Sim Sim Sim
Suporte a FB 3.0 Sim Sim Não
Suporte a FB 4.0 Sim Sim Sim
Suporte a FB 5.0 Sim Sim Sim
Workers paralelos do gbak (FB 5) Sim Não Não
Log shipping de journal Não Não Sim
RPO próximo de zero Não Baixo Sim

6. Guia de instalação

6.1 Pré-requisitos

  • Bacula Community 15.0.3 ou posterior instalado e bacula-fd em execução
  • Servidor Firebird 3.0, 4.0 ou 5.0 (ou embarcado) instalado
  • Binários gbak e nbackup disponíveis no $PATH (ou caminhos completos especificados na configuração do plugin)
  • SO: RHEL/OL/Rocky 9+ ou Ubuntu 22.04+/Debian 12+
  • glibc 2.34+
  • Usuário bacula existente com acesso de leitura aos arquivos do banco de dados Firebird

6.2 Instalação via RPM (EL9 / OL9 / RHEL9 / Rocky 9)

# 1. Install the RPM
dnf install podheitor-firebird-0.1.0-1.el9.x86_64.rpm

# 2. Verify files are in place
ls -la /opt/bacula/plugins/podheitor-firebird-fd.so
ls -la /opt/bacula/bin/podheitor-firebird-backend

# 3. Check state directory was created
ls -la /opt/bacula/working/firebird-state/

# 4. Restart bacula-fd to load the new plugin
systemctl restart bacula-fd

# 5. Confirm plugin loaded (look for "podheitor-firebird" in log)
journalctl -u bacula-fd --since "1 minute ago" | grep podheitor

6.3 Instalação via DEB (Ubuntu 22.04 / Debian 12)

# 1. Install the DEB
apt install ./podheitor-firebird_0.1.0-1_amd64.deb

# 2. Verify files are in place
ls -la /opt/bacula/plugins/podheitor-firebird-fd.so
ls -la /opt/bacula/bin/podheitor-firebird-backend

# 3. Check state directory was created
ls -la /opt/bacula/working/firebird-state/

# 4. Restart bacula-fd
systemctl restart bacula-fd

# 5. Confirm plugin loaded
journalctl -u bacula-fd --since "1 minute ago" | grep podheitor

6.4 Configuração de credenciais

O plugin lê a senha do Firebird a partir de um arquivo de credenciais para evitar que senhas fiquem embutidas na configuração do Bacula:

# Create the credentials file
cat &gt; /opt/bacula/etc/.fbpass &lt;&lt; 'EOF'
SYSDBA=masterkey
EOF

# Secure it
chown bacula:bacula /opt/bacula/etc/.fbpass
chmod 600 /opt/bacula/etc/.fbpass

6.5 Arquivo de configuração do plugin

Crie /opt/bacula/etc/podheitor-firebird.conf:

# PodHeitor Firebird Plugin configuration
[defaults]
fb_user        = "SYSDBA"
fb_host        = "localhost"
fb_port        = 3050
compress       = "zstd"
compress_level = 3
state_dir      = "/opt/bacula/working/firebird-state"

[credentials]
password_file = "/opt/bacula/etc/.fbpass"

6.6 Verificação da instalação

Execute um backup de teste usando bconsole:

*run job=FB-Test-Dump level=Full yes

Esperado: status do job T (terminado normalmente) com valor de bytes gravados diferente de zero.

7. Referência de configuração

7.1 Parâmetros de backup (string Plugin do FileSet)

Parâmetro Padrão Descrição
db (obrigatório) Caminho(s) do banco de dados, separados por vírgula
mode dump Modo de backup: dump / nbackup / replay
level 0 Nível do nbackup (0–3)
workers 1 Workers de backup paralelo (modo dump)
compress zstd Codec de compressão: zstd / lz4 / none
compress_level 3 Nível de compressão zstd (1–22)
bw_limit_kbps 0 Limite de banda em KB/s; 0 = ilimitado
gbak_path gbak Caminho completo do binário gbak (se não estiver no $PATH)
nbackup_path nbackup Caminho completo do binário nbackup (se não estiver no $PATH)
fb_user SYSDBA Nome de usuário do Firebird
fb_password (do .fbpass) Senha do Firebird (prefira o arquivo .fbpass)
fb_host localhost Hostname ou IP do servidor Firebird
fb_port 3050 Porta TCP do servidor Firebird
services_api false Usar conexão via Services API (-se)
embedded false Usar Firebird Embedded (sem servidor necessário)
replay_log_dir (vazio) Diretório de origem dos arquivos de journal de replicação
replay_dest_dir (vazio) Destino de restauração para os arquivos de journal
encrypt_passphrase (vazio) Passphrase de criptografia (repasse via argv para o gbak)
metrics_listen (vazio) Endereço de escuta das métricas Prometheus (ex.: 0.0.0.0:9182); vazio = desabilitado
state_dir /opt/bacula/working/firebird-state Diretório de estado para os manifestos de cadeia do nbackup

7.2 Parâmetros de restauração (string Plugin do Job de Restore)

Parâmetro Padrão Descrição
restore_path (obrigatório) Caminho de destino no sistema de arquivos para o banco de dados restaurado
mode (do backup) Deve corresponder ao modo de backup utilizado
fb_user SYSDBA Nome de usuário do Firebird para operações de restauração
fb_password (do .fbpass) Senha do Firebird
fix_shadow true Executar gfix -sh após a restauração para limpar arquivos shadow
replay_dest_dir (vazio) Diretório para depositar os segmentos de journal restaurados

8. Exemplos de FileSet

8.1 Dump lógico completo

# Full logical dump backup (gbak mode)
FileSet {
  Name = "FB-Dump-Full"
  Include {
    Plugin = "podheitor-firebird: db=/var/firebird/employee.fdb mode=dump compress=zstd workers=2"
  }
}

8.2 Cadeia incremental nbackup

# Level 0 (run weekly or monthly)
FileSet {
  Name = "FB-Nbackup-L0"
  Include {
    Plugin = "podheitor-firebird: db=/var/firebird/prod.fdb mode=nbackup level=0"
  }
}

# Level 1 (run nightly)
FileSet {
  Name = "FB-Nbackup-L1"
  Include {
    Plugin = "podheitor-firebird: db=/var/firebird/prod.fdb mode=nbackup level=1"
  }
}

8.3 Log shipping de replicação

# Replay / journal log shipping
FileSet {
  Name = "FB-Replay-Incr"
  Include {
    Plugin = "podheitor-firebird: db=/var/firebird/prod.fdb mode=replay replay_log_dir=/var/firebird/replay/prod"
  }
}

8.4 Backup paralelo multi-DB

# Four databases backed up in parallel with bandwidth cap
FileSet {
  Name = "FB-MultiDB"
  Include {
    Plugin = "podheitor-firebird: db=/var/firebird/db1.fdb,/var/firebird/db2.fdb,/var/firebird/db3.fdb,/var/firebird/db4.fdb mode=dump workers=4 compress=zstd bw_limit_kbps=51200"
  }
}

8.5 Exemplo de job de restauração

Job {
  Name = "FB-Restore-Employee"
  Type = Restore
  Client = firebird-fd
  FileSet = "FB-Dump-Full"
  Storage = File
  Pool = Default
  Messages = Standard
  Where = /tmp/restore
  Plugin = "podheitor-firebird: mode=dump restore_path=/var/firebird/employee-restored.fdb fix_shadow=true"
}

9. Dimensionamento e planejamento de capacidade

9.1 Requisitos de memória

Cenário FD de base Por worker (dump) nbackup replay
Mínimo 512 MB +128 MB cada +64 MB +64 MB
Dump paralelo com 4 workers 512 MB +512 MB (4×128) — —
Cadeia nbackup de banco grande 512 MB — +64 MB —
Log shipping replay 512 MB — — +64 MB

Exemplo. Um servidor executando dump paralelo com 4 workers em 4 bancos de dados deve ter pelo menos 1,5 GB de RAM alocados ao grupo de processos do bacula-fd.

9.2 Requisitos de CPU

Cenário Núcleos recomendados
Dump de banco único 1
Dump paralelo com 4 bancos 4 (1 por worker)
Cadeia nbackup (qualquer nível) 1
Log shipping replay 1
Métricas Prometheus habilitadas +0,1 (negligível)

9.3 Espaço em disco — binários do plugin

Arquivo Tamanho
podheitor-firebird-fd.so ~580 KB
podheitor-firebird-backend ~516 KB
Footprint total da instalação ~1,1 MB

9.4 Espaço em disco — diretório de estado

Cada banco de dados rastreado pelo modo nbackup armazena um manifesto JSON de aproximadamente 1 KB por entrada de cadeia. Para um ambiente com 100 bancos de dados e cadeias de 4 níveis, o diretório de estado requer cerca de 400 KB — negligível.

9.5 Estimativas de volume de backup

Modo Tamanho esperado (vs. banco bruto)
dump (sem compressão) 60–80% do tamanho do banco
dump (zstd nível 3) 20–45% do tamanho do banco (21,4% observado em lab)
nbackup L0 ~100% do tamanho do banco (somente páginas)
nbackup L1/L2/L3 1–30% do tamanho do banco (somente páginas alteradas)
Segmentos de journal replay < 1% do tamanho do banco por segmento

10. Relatório de desempenho

Todas as medições foram realizadas em ambiente de laboratório controlado usando contêineres Firebird (LI-V3.0.13, LI-V4.0.7, LI-V5.0.4) em um hipervisor KVM/QEMU com Bacula Community 15.0.3.

10.1 Fase 1 — dump e restauração gbak de banco único

Métrica Resultado
Banco de dados employee.fdb (amostra Firebird)
Tamanho do backup 1.536 bytes
Status do job T (terminado normalmente)
Verificação da restauração Byte a byte idêntica
JobId Bacula 7929

10.2 Fase 1b — integridade de dados no ciclo completo de restauração

Métrica Resultado
Linhas gravadas antes do backup 10
Linhas recuperadas após restauração 10
Método de verificação Comparação via SELECT COUNT(*)
Resultado PASS

10.3 Fase 2 — backup paralelo multi-DB

Métrica Sequencial Paralelo (4 workers) Aceleração
Bancos de dados 4–7 4–7 —
Tempo de execução (wall-clock) Base Base / 5,6 5,6×
Razão de compressão zstd — 21,4% on-wire —
Status de todos os jobs T T —

10.4 Fase 3 — cadeia nbackup L0+L1+L2+L3

Nível Tamanho do backup Status
L0 ~875 KB T
L1 ~612 KB T
L2 ~1,1 MB T
L3 ~956 KB T
Total da cadeia 3,5 MB T
Verificação da restauração
Linhas no banco original 13.500
Linhas recuperadas 13.500
Byte a byte idêntico em cada nível Sim

10.5 Fase 4 — gbak com workers paralelos no FB 5 + limitação de banda

Métrica Resultado
Versão do Firebird LI-V5.0.4
Workers paralelos do gbak Habilitado
Meta de banda 64 KB/s
Throughput medido 64,5 KB/s em média
Drift em relação à meta ±0,8%

10.6 Fase 5 — log shipping de replicação

Métrica Resultado
Segmentos de journal enviados 3
Baseline gbak Incluído
Verificação MD5 Byte a byte idêntico no ciclo completo
Status do job T

10.7 Fase 6 — migração entre versões FB 3→5

Métrica Resultado
Origem FB 3.0 (ODS 12)
Destino FB 5.0 (ODS 13)
Linhas preservadas 10
Atualização de ODS Automática via restore do gbak
Verificação gfix Limpo (sem erros)

10.8 Fase 7 — Firebird Embedded + Services API

Teste Resultado
Backup com Firebird Embedded PASS
Backup remoto via Services API (-se) PASS
Ambas as validações de aceitação PASS

10.9 Fase 8 — criptografia, métricas, CLI gc-chain, pacotes

Funcionalidade Resultado
Repasse de argv de criptografia PASS
Endpoint Prometheus /metrics PASS
CLI gc-chain (GC de manifesto nbackup) PASS
Build do pacote RPM PASS
Build do pacote DEB PASS

10.10 Resumo da suíte de testes

Fase Testes adicionados Total acumulado
Fase 0 (bootstrap) 0 0
Fase 1 (dump E2E) 6 6
Fase 1b (ciclo completo de restauração) 4 10
Fase 2 (multi-DB paralelo) 17 27
Fase 3 (cadeia nbackup) 13 40
Fase 4 (FB5 paralelo + BW) 16 56
Fase 5 (replay/log shipping) 6 62
Fase 6 (entre versões) 25 87
Fase 7 (embedded + svc API) 19 106
Fase 8 (encrypt + metrics + pkg) 14 120

11. Matriz de compatibilidade

11.1 Sistema operacional

SO Arquitetura Status
RHEL 9 x86_64 Suportado
Oracle Linux 9 x86_64 Suportado
Rocky Linux 9 x86_64 Suportado
AlmaLinux 9 x86_64 Suportado
Ubuntu 22.04 LTS x86_64 Suportado
Debian 12 x86_64 Suportado
RHEL 8 / CentOS 8 x86_64 Não testado (glibc < 2.34)
Ubuntu 20.04 x86_64 Não testado (glibc < 2.34)
ARM64 / aarch64 qualquer Ainda não disponível

11.2 Versões do Firebird

Versão do Firebird ODS dump nbackup replay
3.0.x (LI-V3.0.13 testado) 11/12 Sim Sim Não
4.0.x (LI-V4.0.7 testado) 12 Sim Sim Sim
5.0.x (LI-V5.0.4 testado) 13 Sim Sim Sim

11.3 Versões do Bacula

Versão do Bacula Status
Community 15.0.3 Suportado (validado)
Community 15.0.x (futuras) Compatível esperado
Community 14.x Não suportado
Bacula Enterprise Não necessário; o plugin tem como alvo o Bacula Community

11.4 Bibliotecas do sistema

Biblioteca Versão mínima
glibc 2.34
libpthread incluída no glibc
libdl incluída no glibc

12. Segurança

12.1 Gerenciamento de credenciais

As senhas do Firebird nunca são armazenadas na configuração de Job ou FileSet do Bacula. A abordagem recomendada é um arquivo de credenciais dedicado:

/opt/bacula/etc/.fbpass
  Owner: bacula:bacula
  Mode:  0600
  Format: USERNAME=password (one per line)

O plugin lê esse arquivo no início do job, antes de executar o backend. A senha é repassada ao gbak/nbackup via variável de ambiente do processo, não como argumento de linha de comando, para evitar exposição na saída do ps.

12.2 Passphrase de criptografia

O parâmetro encrypt_passphrase repassa uma chave de criptografia para o argv nativo de criptografia do gbak. Trata-se de um repasse via argv — o plugin não implementa uma camada de criptografia própria. Os operadores que utilizam esse recurso devem garantir que:

  • A passphrase seja armazenada no arquivo .fbpass, não inline na configuração do FileSet
  • A passphrase nunca seja registrada em log (o plugin a remove de toda a saída de log)
  • A mesma passphrase esteja disponível no momento da restauração

12.3 Permissões do diretório de estado

O diretório de estado /opt/bacula/working/firebird-state/ é criado com:

Owner: bacula:bacula
Mode:  0750

Apenas o usuário bacula e membros do grupo bacula podem ler ou gravar manifestos de cadeia. Isso impede a enumeração não autorizada dos caminhos de bancos de dados com backup.

12.4 Isolamento do processo backend

O cdylib executa um processo backend por job Bacula. O backend herda apenas as credenciais e a configuração necessárias para aquele job. Nenhum estado mutável compartilhado existe entre jobs de backup concorrentes. Se o backend travar ou for encerrado, o cdylib reporta uma falha no job e o bacula-fd continua atendendo outros jobs normalmente.

12.5 Segurança de rede

O plugin utiliza o próprio protocolo TCP do Firebird para conectar ao servidor de banco de dados. Não abre nenhuma porta de escuta adicional. O endpoint opcional de métricas Prometheus (metrics_listen) é um endpoint HTTP somente leitura que expõe apenas contadores operacionais; não expõe credenciais nem conteúdo de dados.

Os operadores devem restringir o acesso à porta de métricas usando regras de firewall:

# Allow metrics access from monitoring host only
firewall-cmd --add-rich-rule='rule family=ipv4 source address=192.168.1.100 port port=9182 protocol=tcp accept' --permanent
firewall-cmd --reload

13. Monitoramento

13.1 Endpoint de métricas Prometheus

Quando metrics_listen é definido na string Plugin, o backend expõe um endpoint /metrics no formato de texto do Prometheus. Exemplo de configuração:

Plugin = "podheitor-firebird: db=/var/firebird/prod.fdb mode=dump metrics_listen=0.0.0.0:9182"

13.2 Métricas expostas

Métrica Tipo Descrição
podheitor_firebird_backup_jobs_total Counter Total de jobs de backup iniciados
podheitor_firebird_backup_bytes_total Counter Total de bytes transmitidos ao Bacula
podheitor_firebird_backup_duration_seconds Histogram Duração de backup por job
podheitor_firebird_restore_jobs_total Counter Total de jobs de restauração iniciados
podheitor_firebird_restore_duration_seconds Histogram Duração de restauração por job
podheitor_firebird_nbackup_chain_levels Gauge Profundidade atual da cadeia nbackup por banco
podheitor_firebird_compression_ratio Gauge Razão de compressão mais recente
podheitor_firebird_bandwidth_kbps Gauge Throughput instantâneo medido
podheitor_firebird_errors_total Counter Total de eventos de erro por código de erro

13.3 Configuração de scrape do Prometheus

scrape_configs:
  - job_name: 'podheitor-firebird'
    static_configs:
      - targets: ['firebird-host:9182']
    scrape_interval: 30s

13.4 Monitoramento de jobs Bacula

Aplica-se o monitoramento padrão do Bacula. O plugin define os códigos de status de job Bacula adequados:

  • T — terminado normalmente
  • E — terminado com erros (o plugin detalha no bacula-fd.log)
  • f — erro fatal (o backend falhou ao iniciar ou travou)

Consulte /opt/bacula/log/bacula-fd.log para mensagens detalhadas do plugin.

14. Guia de solução de problemas

14.1 Erros comuns

Plugin não encontrado na inicialização

Error: cannot open shared object file: No such file or directory

Causa. O podheitor-firebird-fd.so não está no diretório de plugins configurado.
Solução. Verifique se /opt/bacula/plugins/podheitor-firebird-fd.so existe e confira a diretiva PluginDirectory no bacula-fd.conf.

Falha ao iniciar o backend

podheitor-firebird: failed to fork backend: No such file or directory

Causa. O binário podheitor-firebird-backend está ausente ou sem permissão de execução.
Solução:

ls -la /opt/bacula/bin/podheitor-firebird-backend
chmod 755 /opt/bacula/bin/podheitor-firebird-backend

Conexão ao Firebird recusada

podheitor-firebird: gbak error: unavailable database

Causa. O servidor Firebird não está em execução, ou fb_host/fb_port está incorreto.
Solução:

systemctl status firebird
# or for SuperServer:
/opt/firebird/bin/fbguard -pidfile /tmp/firebird.pid &amp;

Senha incorreta

podheitor-firebird: gbak error: Your user name and password are not defined

Causa. O arquivo .fbpass está ausente, ilegível ou contém credenciais incorretas.
Solução:

cat /opt/bacula/etc/.fbpass   # verify content
stat /opt/bacula/etc/.fbpass  # verify permissions (must be 600, owner bacula)

Cadeia nbackup corrompida / L0 ausente

podheitor-firebird: nbackup restore error: cannot find level 0 backup

Causa. A entrada L0 da cadeia está ausente do manifesto de estado, ou o volume Bacula correspondente expirou.
Solução. Execute um novo job de backup L0 para reiniciar a cadeia:

*run job=FB-Nbackup-L0 level=Full yes

Incompatibilidade de versão do glibc

version 'GLIBC_2.34' not found

Causa. O glibc do host é mais antigo que 2.34 (comum no RHEL 8 / Ubuntu 20.04).
Solução. O plugin requer glibc 2.34+. Atualize para RHEL 9 / Rocky 9 / Ubuntu 22.04 ou posterior.

14.2 Localização dos logs

Log Caminho
Log principal do bacula-fd /opt/bacula/log/bacula-fd.log
Saída de debug do plugin incorporado no bacula-fd.log; prefixo podheitor-firebird:
Mensagens Bacula conforme configurado no recurso Messages do bacula-fd.conf
Log do servidor Firebird /opt/firebird/firebird.log

14.3 Habilitando o log de debug

Adicione debug=9 à string Plugin para habilitar a saída detalhada do plugin:

Plugin = "podheitor-firebird: db=/var/firebird/prod.fdb mode=dump debug=9"

Isso registrará cada frame PTCOMM, cada invocação do gbak e todas as transições de estado no bacula-fd.log.

15. Casos de uso e cenários de implantação

15.1 Backup noturno de sistema ERP

Cenário. Uma empresa de manufatura executa o ERP Totvs Protheus no Firebird 4.0 com 12 bancos de dados que variam de 2 GB a 45 GB. Necessitam de backups completos noturnos com retenção de 30 dias.

Solução.

  • Modo: dump com compress=zstd workers=4
  • Agendamento: diariamente às 01:00
  • Retenção: 30 dias em pool Bacula
  • Janela de backup estimada: ~3 horas para os 12 bancos em lotes paralelos de 4

FileSet.

Plugin = "podheitor-firebird: db=/data/protheus/db1.fdb,/data/protheus/db2.fdb,/data/protheus/db3.fdb,/data/protheus/db4.fdb mode=dump workers=4 compress=zstd"

15.2 Banco de dados grande com incremental nbackup

Cenário. Uma empresa de logística possui um banco de dados Firebird de 200 GB que não pode ser completamente copiado todas as noites dentro da janela de backup.

Solução.

  • Semanal: L0 (snapshot completo de páginas) — domingo às 02:00
  • Noturno: L1 (páginas alteradas) — segunda a sábado às 02:00
  • Mensal: reiniciar a cadeia com novo L0 — primeiro domingo do mês

Benefícios. A janela de backup noturno é reduzida de horas para minutos; a restauração completa requer apenas L0 + L1 mais recente.

15.3 Standby de DR com log shipping de replicação

Cenário. Uma empresa de serviços financeiros exige RPO < 5 minutos para seu banco de dados de transações Firebird 5.0.

Solução.

  • Modo: replay com replay_log_dir=/var/firebird/replay/transactions
  • Segmentos de journal enviados a cada 5 minutos via agendamento Bacula
  • Site standby aplica journals automaticamente na restauração
  • RTO: ~15 minutos (tempo para executar restore do gbak + aplicar journals pendentes)

15.4 Projeto de migração entre versões

Cenário. Uma empresa está migrando do Firebird 3.0 para o Firebird 5.0 em 30 bancos de dados. Precisam de um processo testado e repetível.

Solução.

  • Fazer backup dos 30 bancos de dados no FB 3.0 usando o modo dump
  • Restaurar em hosts FB 5.0 usando restore_path — o gbak atualiza automaticamente ODS 12→13
  • Execução pós-restauração do gfix (habilitado por padrão via fix_shadow=true)
  • Verificado com verificações de esquema e dados via isql

15.5 Backup de aplicação com Firebird Embedded

Cenário. Um dispositivo gateway IoT executa um banco de dados Firebird embarcado localmente, sem processo de servidor Firebird. O dispositivo executa bacula-fd e o plugin deve fazer backup do banco embarcado.

Solução.

  • Modo: dump embedded=true
  • O plugin conecta-se diretamente ao arquivo de banco de dados via motor Firebird Embedded
  • Nenhum processo de servidor é necessário; o backup é executado enquanto a aplicação está em quiesce
Plugin = "podheitor-firebird: db=/data/device.fdb mode=dump embedded=true compress=lz4"

16. Comparação com outras abordagens

16.1 Comparação de funcionalidades

A tabela abaixo compara o plugin PodHeitor Firebird executando no Bacula Community com formas alternativas de proteger dados Firebird em plataformas de backup empresarial comerciais. O Bacula Enterprise é incluído como referência: oferece backup empresarial de uso geral excelente e continua sendo uma escolha forte quando recursos mais amplos do BEE são necessários; este plugin foi desenvolvido especificamente para entregar funcionalidade Firebird dedicada (cadeia nbackup, log shipping replay, migração entre versões, suporte ao motor embarcado) na base do Bacula Community.

Funcionalidade Bacula Community + PodHeitor Bacula Enterprise Veeam Commvault
Backup nativo para Firebird Sim Limitado Não Não
Dump lógico gbak Sim Varia por versão Não Não
Cadeia page-level nbackup Sim Não Não Não
Log shipping de replicação Sim Não Não Não
Multi-DB paralelo Sim Não Não Não
Compressão (zstd/lz4) Sim Sim (gzip) Sim Sim
Limitação de banda Sim Sim Sim Sim
Métricas Prometheus Sim Não Não Não
Migração entre versões Sim Não Não Não
Firebird Embedded Sim Não Não Não
Services API Sim Parcial Não Não
FB 3.0 / 4.0 / 5.0 Todos os 3 Varia Não Não
Compatibilidade com Bacula Community Sim N/A N/A N/A
Plataforma base open-source Sim (Bacula CE) Não Não Não
Repasse de criptografia Sim Sim Sim Sim
Restauração byte a byte idêntica Sim Sim Varia Varia
Pacotes RPM + DEB Sim Sim Sim Sim

16.2 Comparação de custos

Oferta especial. Traga sua proposta de renovação do Veeam, Commvault, NetBackup ou qualquer outra plataforma de backup empresarial. Elaboraremos uma proposta formal de comparação direta visando economia mínima de 50%, com funcionalidade superior e específica para Firebird. Contato: heitor@opentechs.lat.

Solução Custo anual típico Suporte ao Firebird
Bacula Community + plugin PodHeitor Significativamente menor Nativo completo (este plugin)
Bacula Enterprise Frequentemente > US$ 10.000/ano Limitado
Veeam Data Platform Frequentemente > US$ 5.000/ano Nenhum (apenas via scripts)
Commvault Frequentemente > US$ 15.000/ano Nenhum (apenas via scripts)
NetBackup Frequentemente > US$ 20.000/ano Nenhum (apenas via scripts)

Os preços variam conforme o tamanho do ambiente e contratos negociados. Contate heitor@opentechs.lat para uma comparação específica com sua proposta de renovação atual.

17. Roadmap

O plugin está pronto para produção na versão v0.1.0 com todas as 8 fases validadas. O direcionamento futuro de desenvolvimento inclui:

  • Suporte a múltiplas arquiteturas. Pacotes ARM64 / aarch64 para Raspberry Pi e servidores ARM cloud-native.
  • Suporte a Windows. O Firebird no Windows é amplamente implantado; um build para Windows está em consideração.
  • Compatibilidade com Firebird 6.0. Acompanhamento das mudanças de ODS nas próximas versões do Firebird.
  • Métricas estendidas. Histórico de backup por banco, scores de saúde da cadeia, limites de alertas automatizados.
  • Integração com interface web. Painel de configuração do plugin no Bacularis para os parâmetros do plugin.
  • Validação automatizada de cadeia. Verificação periódica em segundo plano da integridade da cadeia nbackup.

Não há datas de lançamento comprometidas. O direcionamento das funcionalidades é guiado pelo feedback dos clientes e pelos resultados do laboratório.

18. Conclusão

O PodHeitor Firebird Backup Plugin estende o Bacula Community com a primeira integração production-grade e nativa para Firebird disponível na plataforma open-source Bacula. Entrega três modos de backup complementares (dump, nbackup, replay), cobre todas as versões suportadas do Firebird (3.0, 4.0, 5.0) e foi validado por 120 testes automatizados em 8 fases de desenvolvimento. O resultado é um caminho robusto, auditável e econômico para DR Firebird em nível enterprise.

Para organizações que já executam Bacula Community com bancos de dados Firebird, o plugin não exige nenhuma mudança de plataforma — instale o RPM ou DEB, adicione uma string Plugin ao seu FileSet e seus bancos de dados Firebird estarão protegidos imediatamente. Para organizações avaliando renovações de plataformas de backup comerciais premium, a combinação de Bacula Community e o plugin PodHeitor entrega funcionalidade Firebird igual ou superior com um custo total substancialmente menor.

Para começar:

  • Baixe o plugin: https://podheitor.com
  • Solicite uma proposta ou demonstração: heitor@opentechs.lat
  • Telefone / WhatsApp: +1 786 726-1749 | +55 61 98268-4220

19. Informações de contato

Autor Heitor Faria
Website https://podheitor.com
Email heitor@opentechs.lat
Telefone / WhatsApp +1 786 726-1749
Telefone / WhatsApp (BR) +55 61 98268-4220
Página do produto https://podheitor.com/firebird-plugin
Suporte heitor@opentechs.lat

20. Legal / direitos autorais

© 2026 Heitor Faria — todos os direitos reservados.

O PodHeitor Firebird Backup Plugin for Bacula é software proprietário. Cópia, distribuição, modificação ou engenharia reversa não autorizadas são estritamente proibidas. Uma licença comercial é obrigatória para uso em produção.

Bacula® é marca registrada de Kern Sibbald e da comunidade Bacula. Firebird® é marca registrada do Projeto Firebird. Todas as demais marcas são propriedade de seus respectivos detentores.

Este documento é fornecido para fins informativos. Os dados de desempenho são provenientes de medições em laboratório controlado e podem variar em ambientes de produção conforme o hardware, as condições de rede, a configuração do Firebird e as características do banco de dados.

Contato para licenciamento: heitor@opentechs.lat | https://podheitor.com | +1 786 726-1749 | +55 61 98268-4220

PodHeitor Firebird Backup Plugin for Bacula — v0.1.0 — © 2026 Heitor Faria — todos os direitos reservados — https://podheitor.com

Disponível em: pt-brPortuguêsenEnglish (Inglês)esEspañol (Espanhol)

Deixe um comentário