Referência de Configuração YAML

Este documento fornece uma referência completa para o arquivo config.yaml usado pelo OmniRoam.

Índice

• Estrutura da Configuração
• Configuração Global
  • Configuração TAC
  • PLMNs de Origem
  • Configurações do Processador CDR
  • Caminhos de Arquivos
  • Exportadores
  • Configuração do InfluxDB
  • Registro
• Configuração do Parceiro
  • Prefixos IMSI
  • Configuração de Tarifas
  • Informações de Lote
  • Níveis de Tipo de Chamada
• Exemplo Completo de Configuração
• Contadores de Sequência (counters.yaml)

Estrutura da Configuração

O arquivo config.yaml tem duas seções principais:

config:
  # Configuração global do sistema

partners:
  # Configurações específicas do parceiro

Configuração Global

Configuração TAC

Mapeia Códigos de Área de Rastreamento (TACs) para informações de localização de serviço para geração de arquivos TAP.

config:
  tac_config:
    LocationName:
      tac_list: ['1101', '10000', '10100']
      servingBid: 72473
      servingLocationDescription: 'Exemplo de Rede EUA'
      timezone: 'America/New_York'

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
tac_list	Lista de strings	Sim	Lista de valores TAC que correspondem a esta configuração
timezone	String	Sim	Identificador de fuso horário IANA para cálculo de deslocamento UTC
servingBid	Inteiro	Não	ID de Cobrança de 5 dígitos para saída TAP. Se omitido, BID é excluído do arquivo TAP
servingLocationDescription	String	Não	Descrição de localização legível por humanos

Notas:

• De acordo com a especificação TAP3.12, geographicalLocation é opcional
• Se o TAC de um CDR não corresponder a nenhuma entrada, o sistema usa cdr_processor_tz como o fuso horário padrão
• CDRs sem TAC correspondente não incluirão BID/localização na saída TAP

Exemplo com múltiplas localizações:

config:
  tac_config:
    Global:
      tac_list: ['1101', '10000', '10100', '10200', '1024']
      servingBid: 72473
      servingLocationDescription: 'Exemplo de Rede EUA'
      timezone: 'America/New_York'
    LabNetwork:
      tac_list: ['100']
      servingBid: 46002
      servingLocationDescription: 'Exemplo de Laboratório'
      timezone: 'America/New_York'

PLMNs de Origem

Lista de PLMNs de origem (Redes Móveis Públicas) para o operador.

config:
  home_plmns:
    - '313380'
    - '310260'

Formato: código PLMN de 5 ou 6 dígitos (MCC + MNC)

• MCC: Código do País Móvel (3 dígitos)
• MNC: Código da Rede Móvel (2 ou 3 dígitos)

Configurações do Processador CDR

config:
  cdr_processor_name: Brewster_TAP_1
  cdr_processor_tz: America/New_York

Parâmetros:

Parâmetro	Tipo	Descrição
cdr_processor_name	String	Identificador para esta instância de processamento de CDR
cdr_processor_tz	String	Fuso horário padrão para timestamps de arquivos e CDRs sem TAC correspondente

Caminhos de Arquivos

Configure caminhos de entrada e saída para processamento de CDR.

config:
  cdr_search_paths:
    - '/var/Athonet_CDRs/'
    - '/var/OmniCore_CDRs/'
  tap_output_path: '/etc/pytap3/OutputFiles'
  tap_human_readable_output_path: '/etc/pytap3/OutputFiles_Human'
  tap_in_path: '/home/nick/Documents/PyTAP/TAP_In/'

Parâmetros:

Parâmetro	Tipo	Descrição
cdr_search_paths	Lista de strings	Diretórios a serem escaneados para arquivos CDR recebidos
tap_output_path	String	Diretório de saída para arquivos TAP3 binários
tap_human_readable_output_path	String	Diretório de saída para arquivos TAP3 legíveis por humanos
tap_in_path	String	Diretório para arquivos TAP3 recebidos (para processamento RAP)

Filtro de Nome de Arquivo de Roaming

config:
  roaming_in_filename: False

Parâmetro:

Parâmetro	Tipo	Padrão	Descrição
roaming_in_filename	Booleano	False	Se True, processa apenas arquivos CDR com "roaming" no nome do arquivo

Configurações de Visualização de CDR Bruto

config:
  raw_cdr_view_max_age: 7

Parâmetro:

Parâmetro	Tipo	Unidade	Descrição
raw_cdr_view_max_age	Inteiro	Dias	Idade máxima dos arquivos visíveis na visualização de CDRs Brutos na interface da Web

Exportadores

Configure quais exportadores estão habilitados para saída de CDR.

config:
  exporters:
    - CSVExporter
    - Aria
    - virtual_exporter

Exportadores Disponíveis:

• CSVExporter: Exporta CDRs para o formato CSV
• Aria: Exporta para o sistema de cobrança Aria
• virtual_exporter: Exportador virtual/teste

Configuração do InfluxDB

Configure a conexão com o InfluxDB para métricas e monitoramento.

config:
  influx_db:
    influxDbUrl: 'http://10.3.0.135:8086'
    influxDbOrg: 'omnitouch'
    influxDbBucket: 'Omnicharge_TAP3'
    influxDbToken: 'your-token-here'

Parâmetros:

Parâmetro	Tipo	Descrição
influxDbUrl	String	URL do servidor InfluxDB incluindo protocolo e porta
influxDbOrg	String	Nome da organização InfluxDB
influxDbBucket	String	Nome do bucket InfluxDB para armazenar métricas
influxDbToken	String	Token de autenticação para acesso à API InfluxDB

Nota de Segurança: Considere usar variáveis de ambiente ou gerenciamento de segredos para o token em ambientes de produção.

Registro

config:
  log_level: DEBUG

Níveis de Log Válidos:

• DEBUG: Informações detalhadas para diagnosticar problemas
• INFO: Confirmação de que as coisas estão funcionando como esperado
• WARNING: Indicação de eventos inesperados
• ERROR: Problemas sérios que impedem a funcionalidade
• CRITICAL: Erros muito sérios que podem causar a terminação do programa

Configuração do Parceiro

Cada parceiro de roaming requer um bloco de configuração sob a seção partners:.

Estrutura Básica do Parceiro

partners:
  PartnerName_Live:
    imsi_prefixes:
      - '311480'
    accessPointNameOI: mnc480.mcc311.gprs
    rates:
      unit_price: 0.000476800
      unit_bytes: 1024
    batch_info:
      sender: USAFU
      recipient: USAVZ
      specificationVersionNumber: 3
      releaseVersionNumber: 12
      accountingInfo:
        localCurrency: 'USD'
        tapCurrency: 'USD'
        roundingAction: 'Simple'
        tapDecimalPlaces: 5
    round_up_to: 1024
    call_type_level:
      qci_1: 20
      qci_2: 22
      default: 20

Prefixos IMSI

partners:
  VZW_Live:
    imsi_prefixes:
      - '311480'

  VZW_Test:
    imsi_prefixes:
      - '311480616872353'
      - '311480616860347'

Como Funciona a Correspondência de Prefixos IMSI:

O OmniRoam usa a lógica de correspondência do mais longo primeiro para corresponder CDRs a parceiros:

1. Extraia o IMSI do CDR (por exemplo, 311480616872353)
2. Avalie todas as configurações de parceiros
3. Encontre o prefixo correspondente mais longo
4. Aplique as tarifas e configurações desse parceiro

Exemplo de Correspondência:

• IMSI 311480616872353 → Corresponde a VZW_Test (prefixo de 15 dígitos é mais longo)
• IMSI 311480123456789 → Corresponde a VZW_Live (prefixo de 6 dígitos)

Caso de Uso - Separação de SIM de Teste:

Isso permite um tratamento diferente para tráfego de teste e produção:

partners:
  ATT_Test:
    imsi_prefixes:
      - '310410966551547'  # SIM de teste específico (15 dígitos)
      - '310410966551546'
    rates:
      unit_price: 0.0  # Sem cobrança para tráfego de teste
    batch_info:
      sender: USAFU
      recipient: USACGTEST  # Código TADIG de teste
      fileTypeIndicator: T   # Marcador de arquivo de teste

  ATT_Live:
    imsi_prefixes:
      - '310410'  # Faixa de produção (6 dígitos)
    rates:
      unit_price: 0.000476800
    batch_info:
      sender: USAFU
      recipient: USACG  # Código TADIG de produção

Nome do Ponto de Acesso OI

accessPointNameOI: mnc480.mcc311.gprs

Formato: mnc{MNC}.mcc{MCC}.gprs

• Usado em arquivos TAP3 para identificar a estrutura APN do operador

Configuração de Tarifas

rates:
  unit_price: 0.000476800
  unit_bytes: 1024

Parâmetros:

Parâmetro	Tipo	Descrição
unit_price	Decimal	Preço por unidade na moeda configurada (por exemplo, USD)
unit_bytes	Inteiro	Número de bytes por unidade de cobrança

Exemplo de Cálculo de Tarifas:

Uso: 52,428,800 bytes (50 MB)
Tamanho da Unidade: 1024 bytes
Unidades: 52,428,800 ÷ 1024 = 51,200 unidades
Tarifa: $0.000476800 por 1KB
Cobrança: 51,200 × $0.000476800 = $24.41
Unidades TAP: 24,410 (multiplicadas por 1000 para o formato TAP3)

Arredondamento de Uso

round_up_to: 1024

Parâmetro:

Parâmetro	Tipo	Descrição
round_up_to	Inteiro	Arredonda o uso total para o número mais próximo de N bytes antes da cobrança

Exemplo:

• Uso real: 1500 bytes
• round_up_to: 1024
• Uso arredondado: 2048 bytes (2 × 1024)

Informações de Lote

Configuração para informações de controle de lote de arquivos TAP3.

batch_info:
  sender: USAFU
  recipient: USAVZ
  specificationVersionNumber: 3
  releaseVersionNumber: 12
  fileTypeIndicator: T
  accountingInfo:
    localCurrency: 'USD'
    tapCurrency: 'USD'
    roundingAction: 'Simple'
    tapDecimalPlaces: 5

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
sender	String	Sim	Código TADIG de 5 caracteres para o operador remetente
recipient	String	Sim	Código TADIG de 5 caracteres para o operador destinatário
specificationVersionNumber	Inteiro	Sim	Versão da especificação TAP (geralmente 3)
releaseVersionNumber	Inteiro	Sim	Versão de lançamento TAP (por exemplo, 11, 12)
fileTypeIndicator	String	Não	Definido como T para arquivos de teste. Omitir para arquivos de produção

Indicador de Tipo de Arquivo:

• Se definido como T: O prefixo do nome do arquivo TAP é TD (Dados de Teste) e o arquivo é marcado como teste
• Se omitido: O prefixo do nome do arquivo TAP é CD (Dados Comerciais)

Informações de Contabilidade:

Parâmetro	Tipo	Valores	Descrição
localCurrency	String	ISO 4217	Código da moeda para contabilidade local (por exemplo, 'USD', 'EUR', 'GBP')
tapCurrency	String	ISO 4217	Código da moeda para cobranças do arquivo TAP
roundingAction	String	'Up', 'Down', 'Simple'	Como arredondar cobranças calculadas
tapDecimalPlaces	Inteiro	0-5	Número de casas decimais para os valores de cobrança TAP

Ações de Arredondamento:

• Up: Sempre arredonda cobranças para cima
• Down: Sempre arredonda cobranças para baixo
• Simple: Arredondamento padrão (0.5 e acima arredonda para cima)

Níveis de Tipo de Chamada

Mapeia valores QCI (Identificador de Classe de QoS) para Níveis de Tipo de Chamada TAP3.

call_type_level:
  qci_1: 20
  qci_2: 22
  qci_3: 23
  qci_4: 24
  qci_5: 25
  qci_6: 26
  qci_7: 27
  qci_8: 28
  qci_9: 29
  default: 20

Mapeamentos QCI Padrão:

QCI	Tipo de Serviço	Nível de Tipo de Chamada Típico
qci_1	Voz Conversacional	20 ou 21
qci_2	Vídeo Conversacional	22
qci_3	Jogos em Tempo Real	23
qci_4	Streaming em Buffer	24
qci_5	Sinalização IMS	20 ou 25
qci_6	Navegação Interativa	26
qci_7	Jogos Interativos	27
qci_8	Em Segundo Plano	28
qci_9	Em Segundo Plano Baixa Prioridade	29
default	Não Especificado/Desconhecido	20

Nota: O sistema usa o valor default quando o QCI do CDR não corresponde a nenhum mapeamento configurado.

Exemplo Completo de Configuração

O seguinte exemplo completo mostra tanto configurações de teste quanto de produção:

config:
  tac_config:
    Global:
      tac_list: ['1101', '10000', '10100', '10200', '1024']
      servingBid: 72473
      servingLocationDescription: 'Exemplo de Rede EUA'
      timezone: 'America/New_York'
    ExampleLab:
      tac_list: ['100']
      servingBid: 46002
      servingLocationDescription: 'Exemplo de Laboratório'
      timezone: 'America/New_York'

  home_plmns:
    - '313380'

  cdr_processor_name: Brewster_TAP_1
  cdr_processor_tz: America/New_York

  cdr_search_paths:
    - '/var/Athonet_CDRs/'
    - '/var/OmniCore_CDRs/'

  tap_output_path: '/etc/pytap3/OutputFiles'
  tap_human_readable_output_path: '/etc/pytap3/OutputFiles_Human'
  tap_in_path: '/home/user/TAP_In/'

  roaming_in_filename: False
  raw_cdr_view_max_age: 7

  exporters:
    - CSVExporter
    - Aria
    - virtual_exporter

  influx_db:
    influxDbUrl: 'http://10.3.0.135:8086'
    influxDbOrg: 'omnitouch'
    influxDbBucket: 'Omnicharge_TAP3'
    influxDbToken: 'your-secure-token-here'

  log_level: DEBUG

partners:
  # Configuração de SIM de Teste - IMSIs Específicos
  VZW_Test:
    imsi_prefixes:
      - '311480616872353'
      - '311480616860347'
    accessPointNameOI: mnc480.mcc311.gprs
    rates:
      unit_price: 0.000476800
      unit_bytes: 1024
    batch_info:
      sender: USAFU
      recipient: USAVZ
      specificationVersionNumber: 3
      releaseVersionNumber: 12
      fileTypeIndicator: T
      accountingInfo:
        localCurrency: 'USD'
        tapCurrency: 'USD'
        roundingAction: 'Simple'
        tapDecimalPlaces: 5
    round_up_to: 1024
    call_type_level:
      qci_1: 21
      qci_2: 22
      qci_3: 23
      qci_4: 24
      qci_5: 25
      qci_6: 26
      qci_7: 27
      qci_8: 28
      qci_9: 29
      default: 20

  # Configuração de Produção - Prefixo IMSI
  VZW_Live:
    imsi_prefixes:
      - '311480'
    accessPointNameOI: mnc480.mcc311.gprs
    rates:
      unit_price: 0.000476800
      unit_bytes: 1024
    batch_info:
      sender: USAFU
      recipient: USAVZ
      specificationVersionNumber: 3
      releaseVersionNumber: 12
      accountingInfo:
        localCurrency: 'USD'
        tapCurrency: 'USD'
        roundingAction: 'Simple'
        tapDecimalPlaces: 5
    round_up_to: 1024
    call_type_level:
      qci_1: 20
      qci_2: 22
      qci_3: 23
      qci_4: 24
      qci_5: 20
      qci_6: 26
      qci_7: 27
      qci_8: 28
      qci_9: 29
      default: 20

Contadores de Sequência (counters.yaml)

Os números de sequência do arquivo TAP3 são rastreados separadamente do config.yaml em um arquivo counters.yaml. Cada nome de arquivo TAP3 incorpora um número de sequência de 5 dígitos que deve aumentar monotonamente por remetente/destinatário e tipo de arquivo, portanto, o OmniRoam persiste o último valor usado aqui e o incrementa toda vez que um arquivo é gerado.

O arquivo é um mapa plano com chave pelo código TADIG de 5 caracteres, com um contador separado para cada tipo de arquivo:

AAA00:
  CD: 1     # Sequência de Dados Comerciais
  TD: 1     # Sequência de Dados de Teste
AAA01:
  CD: 11
  TD: 50

Chave	Descrição
Chave de nível superior	Código TADIG de 5 caracteres do parceiro (destinatário)
CD	Próximo número de sequência para arquivos de Dados Comerciais
TD	Próximo número de sequência para arquivos de Dados de Teste

Notas:

• Inicialize um novo parceiro com CD: 1 e TD: 1.
• Os valores são auto-incrementados cada vez que um arquivo TAP é gerado para esse parceiro.
• Os números de sequência não devem exceder 99999 (o limite de campo de 5 dígitos); monitore e redefina em coordenação com o parceiro se um contador se aproximar do limite.
• Faça backup do counters.yaml junto com o config.yaml para que a continuidade da sequência seja preservada em restaurações.

Melhores Práticas de Configuração

1. Organização de Prefixos IMSI

Ordene as configurações do mais específico para o mais geral:

partners:
  # Mais específico - SIMs de teste (15 dígitos)
  ATT_TestSIM1:
    imsi_prefixes:
      - '310410966551547'

  # Menos específico - faixa de produção (6 dígitos)
  ATT_Live:
    imsi_prefixes:
      - '310410'

2. Separação de Teste e Produção

Sempre separe as configurações de teste e produção:

partners:
  Partner_Test:
    imsi_prefixes: ['310410966551547']
    batch_info:
      fileTypeIndicator: T  # Marcar como arquivo de teste
      recipient: USACGTEST  # Usar código TADIG de teste

  Partner_Live:
    imsi_prefixes: ['310410']
    # Sem fileTypeIndicator = produção

3. Configuração TAC

Crie configurações TAC separadas para diferentes localizações:

config:
  tac_config:
    MainNetwork:
      tac_list: ['1101', '10000']
      timezone: 'America/New_York'

    LabNetwork:
      tac_list: ['100', '200']
      timezone: 'America/Chicago'

4. Segurança

Proteja configurações sensíveis:

# Defina permissões restritivas
chmod 600 config.yaml

# Considere usar variáveis de ambiente para tokens
# influxDbToken: ${INFLUX_TOKEN}

5. Backup de Arquivos de Configuração

Backups regulares da configuração:

# Backup antes de alterações
cp config.yaml config.yaml.backup
cp counters.yaml counters.yaml.backup

6. Controle de Versão

Rastreie alterações na configuração:

git add config.yaml
git commit -m "Adicionada nova configuração de parceiro para XYZ"

Resolução de Problemas

CDRs Não Correspondendo ao Parceiro

Problema: CDRs não estão sendo atribuídos ao parceiro correto.

Solução: Verifique a correspondência de prefixos IMSI:

1. Verifique se o IMSI no CDR corresponde a um prefixo configurado
2. Verifique se há prefixos sobrepostos (o mais longo vence)
3. Revise os logs para erros de correspondência de IMSI

Arquivos TAP com Números de Sequência Errados

Problema: Os números de sequência do arquivo TAP estão incorretos.

Solução: Verifique counters.yaml:

USAVZ:
  CD: 123  # Sequência de Dados Comerciais
  TD: 45   # Sequência de Dados de Teste

Informações de Localização Faltando em Arquivos TAP

Problema: Arquivos TAP não incluem BID ou descrição de localização.

Solução:

1. Verifique se o TAC do CDR corresponde a um tac_list configurado
2. Certifique-se de que servingBid está configurado para esse TAC
3. Verifique se a configuração TAC inclui os campos necessários

Erros de Cálculo de Tarifas

Problema: As cobranças não correspondem aos valores esperados.

Solução:

1. Verifique se unit_price e unit_bytes estão corretos
2. Verifique a configuração de roundingAction
3. Revise a configuração de round_up_to
4. Verifique se tapDecimalPlaces corresponde aos requisitos do parceiro

Documentação Relacionada

• README.md - Documentação principal
• Contadores de Sequência (counters.yaml) - Contadores de sequência de arquivos TAP3
• Especificação TAP3 - Padrão GSMA TAP3.12

---

OmniRoam - Gestão profissional de receita de roaming pela Omnitouch.