Guia de Solução de Problemas do OmniSEP

Problemas comuns e resoluções para a Plataforma de Ponto de Serviço OmniSEP.

Índice

• Registro de Atividade
• Problemas de Direito TS.43
• Problemas de Simservs XCAP
• Problemas de Autenticação
• Problemas de Conectividade
• Problemas de Armazenamento

Registro de Atividade

O Registro de Atividade fornece uma visão em tempo real de todas as solicitações ao OmniSEP, incluindo consultas de direito TS.43 e operações XCAP.

Recursos:

• Filtrar por tipo de solicitação (XCAP, Consulta de Direito, Desafio EAP, etc.)
• Pesquisar por IMSI, MSISDN, ID do Terminal ou IP do Cliente
• Ver método HTTP (GET, PUT, POST, DELETE) e status da resposta
• Clique em qualquer linha para ver informações detalhadas

Painel de Detalhes da Atividade

Selecionar um registro de atividade mostra detalhes abrangentes de solicitação/resposta:

Informações Capturadas:

• Timestamp e IP do Cliente: Quando e onde a solicitação se originou
• Tipo de Solicitação e Método HTTP: XCAP, consulta de direito, etc.
• Informações do Assinante: IMSI, MSISDN (quando disponível)
• Informações do Terminal: ID do dispositivo, Fabricante, Modelo (extraído do User-Agent)
• Caminho da Solicitação: Caminho XCAP completo ou endpoint de direito
• User-Agent: Cabeçalho User-Agent bruto
• Cabeçalhos da Solicitação: Content-Type, If-Match, cabeçalhos 3GPP, etc.
• Corpo da Solicitação/Resposta: Conteúdo XML para operações XCAP
• Status da Resposta: Sucesso, Erro do Servidor, Erro do Cliente com código HTTP

Fluxo de Trabalho de Diagnóstico

Problemas de Direito TS.43

Dispositivo Relata "Serviço Não Disponível"

Sintomas: Dispositivo mostra VoWiFi/VoLTE como indisponível apesar da assinatura correta

Causas possíveis:

• Direitos padrão configurados com entitlement_status: 0
• Direito personalizado definido para o assinante com status desativado
• Dispositivo enviando IMSI ou parâmetros de terminal incorretos

Resolução:

1. Verifique o registro de atividade para as solicitações do assinante:

   GET /api/activity?imsi=<subscriber_imsi>

2. Verifique a resposta de direito nos registros de atividade

3. Verifique a configuração de direitos padrão:

   config :omni_sep, :default_entitlements,
     vowifi: %{
       entitlement_status: 1,  # Deve ser 1 para habilitado
       ...
     }

4. Verifique se há direitos personalizados que substituem os padrões:

   GET /api/entitlements/<imsi>

Dispositivo Recebe Status de Direito Incorreto

Sintomas: Dispositivo recebe valores de direito diferentes do esperado

Causas possíveis:

• Direito personalizado configurado para o assinante
• app_id incorreto sendo consultado
• Incompatibilidade de configuração entre ambientes

Resolução:

1. Verifique qual app_id o dispositivo está solicitando (verifique o registro de atividade)

2. IDs de aplicativo comuns:

   App ID	Serviço
   ap2003	VoLTE/VoNR
   ap2004	VoWiFi
   ap2005	SMSoIP

3. Verifique os direitos personalizados:

   GET /api/entitlements/<imsi>

4. Remova o direito personalizado indesejado:

   DELETE /api/entitlements/<imsi>/<app_id>

Parâmetros Faltando na Solicitação

Sintomas: HTTP 400 Bad Request com erro "Parâmetros faltando"

Causas possíveis:

• Dispositivo não enviando os parâmetros TS.43 necessários
• Parâmetros em formato incorreto
• Problemas de codificação de URL

Parâmetros necessários:

Parâmetro	Descrição
terminal_id	IMEI do dispositivo (15 dígitos)
terminal_vendor	Fabricante (máx. 4 caracteres)
terminal_model	Nome do modelo (máx. 10 caracteres)
terminal_sw_version	Versão do software
entitlement_version	Versão do protocolo (tipicamente "2.0")
app	ID(s) do aplicativo a serem consultados

Resolução:

1. Verifique o registro de atividade para detalhes da solicitação bruta
2. Verifique se o dispositivo está enviando todos os parâmetros necessários
3. Para Android, certifique-se de que o User-Agent siga o formato:

   PRD-TS43 term-<vendor>/<model> client-IMS-Entitlement/1.0 OS-Android/<version>

Incompatibilidade de Versão (HTTP 406)

Sintomas: Dispositivo recebe HTTP 406 Not Acceptable

Causas possíveis:

• Dispositivo enviando entitlement_version não suportada
• Servidor configurado com versão incompatível

Resolução:

1. Verifique a versão configurada do servidor:

   config :omni_sep,
     entitlement_version: "2.0"

2. Dispositivos Android normalmente usam a versão "2.0"

3. Certifique-se de que a versão do servidor corresponda à versão esperada do dispositivo

Problemas de Simservs XCAP

Perfil Não Encontrado (HTTP 404)

Sintomas: Solicitação XCAP GET retorna 404

Causas possíveis:

• Perfil nunca criado para o assinante
• Formato de URI SIP incorreto
• MSISDN não vinculado ao perfil

Resolução:

1. Verifique o formato do URI SIP na solicitação:

   /simservs.ngn.etsi.org/users/sip:+<msisdn>@<domain>/simservs.xml

2. Verifique se o perfil existe via API de gerenciamento:

   GET /api/xcap/<msisdn>

3. Crie o perfil se estiver faltando:

   POST /api/xcap/<msisdn>
   Content-Type: application/json
   
   {
     "oip": {"active": true},
     "oir": {"active": true, "default_behaviour": "presentation-not-restricted"},
     "no_reply_timer": 20,
     "call_forwarding": {},
     "call_barring_incoming": {},
     "call_barring_outgoing": {}
   }

Incompatibilidade de ETag (HTTP 412)

Sintomas: Solicitação PUT ou DELETE retorna HTTP 412 Precondition Failed

Causas possíveis:

• Cliente usando ETag obsoleto
• Modificação concorrente por outro cliente
• ETag não enviada com solicitação condicional

Resolução:

1. Busque o documento atual para obter ETag fresca:

   GET /simservs.ngn.etsi.org/users/<sip_uri>/simservs.xml

2. Use a ETag retornada no cabeçalho If-Match:

   PUT /simservs.ngn.etsi.org/users/<sip_uri>/simservs.xml
   If-Match: "<etag_value>"
   Content-Type: application/xcap-el+xml
   
   <simservs>...</simservs>

3. Para atualizações incondicionais (apenas para teste), omita o cabeçalho If-Match

XML Inválido (HTTP 400)

Sintomas: Solicitação PUT retorna HTTP 400 Bad Request

Causas possíveis:

• XML malformado no corpo da solicitação
• Namespaces obrigatórios ausentes
• Estrutura de elemento inválida

Namespaces necessários:

Prefixo	Namespace
(padrão)	http://uri.etsi.org/ngn/params/xml/simservs/xcap
cp	urn:ietf:params:xml:ns:common-policy

Resolução:

1. Valide a estrutura XML

2. Certifique-se de que o elemento raiz inclua os namespaces obrigatórios:

   <simservs xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap"
             xmlns:cp="urn:ietf:params:xml:ns:common-policy">

3. Verifique se os nomes dos elementos correspondem à especificação ETSI TS 183 023

Encaminhamento de Chamadas Não Ativando

Sintomas: Configurações de encaminhamento de chamadas salvas, mas chamadas não são encaminhadas

Causas possíveis:

• Regra desativada no perfil
• Tipo de condição incorreto
• Formato do número de destino incorreto

Resolução:

1. Verifique se communication-diversion está ativo:

   <communication-diversion active="true">

2. Verifique se a regra está estruturada corretamente:

   <cp:rule id="cfb">
     <cp:conditions>
       <busy/>
     </cp:conditions>
     <cp:actions>
       <forward-to>
         <target>tel:+15557654321</target>
       </forward-to>
     </cp:actions>
   </cp:rule>

3. IDs de regra e condições válidos:

   ID da Regra	Condição	Descrição
   cfu	(nenhuma)	Incondicional
   cfb	busy	Em Ocupado
   cfna	no-answer	Sem Resposta
   cfnrc	not-reachable	Não Acessível
   cfnl	not-logged-in	Não Conectado

4. O destino deve usar o formato de URI tel: com número E.164

Problemas de Autenticação

Desafio EAP-AKA Não Retornado

Sintomas: Solicitação inicial com EAP_ID retorna erro em vez de desafio

Causas possíveis:

• EAP-AKA desativado na configuração
• Formato de EAP_ID inválido
• Problemas de conectividade do par Diameter

Resolução:

1. Verifique se o EAP-AKA está habilitado:

   config :omni_sep, :eap_aka,
     enabled: true

2. Verifique o formato do EAP_ID (Root NAI):

   0<IMSI>@nai.epc.mnc<MNC>.mcc<MCC>.3gppnetwork.org

   Exemplo: 0310410123456789@nai.epc.mnc410.mcc310.3gppnetwork.org

3. Se os pares Diameter estiverem configurados, verifique a conectividade

4. Se nenhum par estiver configurado, o modo simulado deve aceitar qualquer formato válido

Token Inválido (HTTP 511)

Sintomas: Solicitação com token retorna HTTP 511 Network Authentication Required

Causas possíveis:

• Token expirado
• Segredo de assinatura do token alterado
• Token gerado por instância diferente

Resolução:

1. Verifique o período de validade do token:

   config :omni_sep, :token,
     validity_seconds: 86400  # 24 horas por padrão

2. Se o segredo foi rotacionado, todos os tokens existentes são invalidados

3. O dispositivo deve voltar à autenticação EAP-AKA para obter um novo token

4. Verifique se todas as instâncias usam o mesmo signing_secret

Incompatibilidade de Assinatura do Token

Sintomas: Token com aparência válida rejeitado

Causas possíveis:

• Token de ambiente diferente
• Incompatibilidade de segredo de assinatura entre instâncias
• Token adulterado

Resolução:

1. Certifique-se de que o signing_secret seja consistente entre todas as instâncias:

   config :omni_sep, :token,
     signing_secret: System.get_env("OMNI_SEP_TOKEN_SECRET")

2. Use variável de ambiente para o segredo em produção

3. Rotacione os segredos em todas as instâncias simultaneamente

Problemas de Conectividade

Serviço Não Acessível

Sintomas: Conexão recusada ou timeout

Causas possíveis:

• Serviço não está em execução
• Configuração de porta incorreta
• Firewall bloqueando tráfego

Resolução:

1. Verifique a saúde do serviço:

   curl http://<host>:9014/health

2. Verifique a configuração da porta:

   config :omni_sep,
     http_port: 9014,
     http_ip: {0, 0, 0, 0}

3. Verifique se as regras do firewall permitem tráfego na porta configurada

4. Verifique se o serviço está ouvindo:

   netstat -tlnp | grep 9014

Verificação de Saúde Retorna Não Saudável

Sintomas: Endpoint /health retorna status não-200

Causas possíveis:

• Serviço dependente indisponível
• Tabelas de armazenamento não inicializadas
• Inicialização do aplicativo incompleta
• Diretório de dados Mnesia não gravável

Resolução:

1. Verifique os logs do aplicativo para erros de inicialização

2. Verifique a inicialização do armazenamento:

   • Tabelas Mnesia (registro de atividade)
   • Tabelas ETS (direitos, tokens, sessões, perfis XCAP)

3. Verifique as permissões do diretório de dados Mnesia:

   ls -la priv/data/mnesia/

4. Se a Mnesia falhar ao iniciar, verifique se há arquivos corrompidos e considere limpar o diretório de dados

5. Reinicie o aplicativo se as tabelas estiverem faltando

Tempos de Resposta Lentos

Sintomas: Solicitações levando mais tempo do que o esperado

Causas possíveis:

• Timeouts de pares Diameter
• Acúmulo de registro de atividade
• Alta carga concorrente

Resolução:

1. Verifique a configuração do par Diameter:

   config :diameter_ex, :diameter,
     request_timeout: 5000  # 5 segundos por padrão

2. Monitore o tamanho do registro de atividade por assinante

3. Verifique o uso de memória da tabela ETS

4. Considere escalonamento horizontal para alta carga

Problemas de Armazenamento

Registro de Atividade Não Persistindo

Sintomas: Registros de atividade perdidos após reinício

Causas possíveis:

• Diretório de dados Mnesia não gravável
• Aplicativo encerrado antes que a Mnesia pudesse gravar no disco
• Disco cheio

Resolução:

1. Verifique se o diretório de dados existe e é grav��vel:

   ls -la priv/data/mnesia/

2. Verifique se há logs de transação Mnesia (.DCL files) - estes contêm gravações recentes:

   ls -la priv/data/mnesia/*.DCL

3. Certifique-se de um desligamento gracioso para permitir que a Mnesia grave:

   # Não use kill -9, use SIGTERM em vez disso
   kill -TERM <pid>

4. Verifique o espaço em disco:

   df -h priv/data/

Esquema Mnesia Corrompido

Sintomas: Aplicativo falha ao iniciar com erros da Mnesia

Causas possíveis:

• Perda de energia ou falha durante gravação
• Corrupção de disco
• Versões misturadas do Erlang

Resolução:

1. Verifique os logs para erro específico da Mnesia

2. Se os dados puderem ser perdidos, limpe e reinicialize:

   rm -rf priv/data/mnesia/*
   # Reinicie o aplicativo - as tabelas serão recriadas

3. Se os dados devem ser preservados, tente reparar a Mnesia:

   :mnesia.stop()
   :mnesia.start()
   :mnesia.wait_for_tables([:activity, :activity_by_imsi, :activity_by_terminal], 30000)

Registro de Atividade Crescendo Demais

Sintomas: Uso de disco aumentando, consultas lentas

Causas possíveis:

• Alto volume de solicitações
• Período de retenção muito longo
• Limite por assinante muito alto

Resolução:

1. Verifique as configurações de retenção atuais:

   config :omni_sep, :activity,
     max_records_per_subscriber: 1000,  # Reduza se necessário
     retention_seconds: 2_592_000       # 30 dias, reduza se necessário

2. Monitore o tamanho da tabela:

   ls -lh priv/data/mnesia/activity.*

3. Considere reduzir o período de retenção para implantações de alto volume

Comandos de Diagnóstico

Verificação de Saúde

curl -s http://localhost:9014/health | jq

Resposta esperada:

{
  "status": "ok",
  "service": "omni-sep",
  "version": "0.1.0",
  "services": ["entitlements", "xcap"]
}

Consulta ao Registro de Atividade

# Atividade recente para assinante
curl "http://localhost:9014/api/activity?imsi=<imsi>&limit=10"

# Atividade por terminal
curl "http://localhost:9014/api/activity?terminal_id=<imei>&limit=10"

# Atividade em intervalo de tempo
curl "http://localhost:9014/api/activity?from=<unix_ts>&to=<unix_ts>"

Verificação de Direitos

# Obter direitos personalizados
curl http://localhost:9014/api/entitlements/<imsi>

# Definir direito personalizado
curl -X POST http://localhost:9014/api/entitlements/<imsi> \
  -H "Content-Type: application/json" \
  -d '{"app_id": "ap2004", "entitlement": {"entitlement_status": 1}}'

Verificação de Perfil XCAP

# Obter perfil
curl http://localhost:9014/api/xcap/<msisdn>

# Obter documento completo simservs
curl "http://localhost:9014/simservs.ngn.etsi.org/users/sip:+<msisdn>@domain/simservs.xml"

Análise de Logs

Padrões de Log Chave

Padrão	Significado
[info] GET / ...	Solicitação de direito recebida
[info] POST / ...	Solicitação POST recebida (EAP ou direito)
[warning] Missing parameters	Validação da solicitação falhou
[error] EAP session timeout	EAP-AKA não concluído a tempo
[debug] Token validated	Autenticação de token bem-sucedida

Habilitando Logging de Depuração

# config/dev.exs ou runtime
config :logger, :console,
  level: :debug,
  metadata: [:request_id, :imsi, :terminal_id]

Especificações de Referência

Para solução de problemas específica do protocolo, consulte:

Protocolo	Especificação
TS.43	GSMA TS.43
XCAP	RFC 4825
Simservs	ETSI TS 183 023
EAP-AKA	RFC 4187
Diameter	RFC 6733