Configuração do medidor#
O medidor SIMET precisa ser configurado, para seu correto funcionamento, conforme descrito a seguir.
Atenção
Incorreções na parametrização, como tabelas DMI com erro de preenchimento ou preenchimento incompleto pelo fabricante ou integrador, geram vício oculto em sondas e roteadores SIMETBox e caracterizam violação dos termos de uso do sistema SIMET .
Nota
O NIC.br dispõe-se a ajudar na verificação final da configuração mediante suporte best-effort por email, ou suporte de desenvolvimento em caso de acordo de cooperação técnica com o fabricante ou integrador.
Nota
1. A parametrização para Raspberry Pi utilizando a versão atual do Raspberry Pi OS ainda está em testes. Sendo esse o caso de interesse, entre em contato para obter instruções específicas. Pacote: simetbox-deb-rpi;
2. Pacotes simetbox-deb-* estão em desenvolvimento. Estes facilitam largamente a parametrização de Sondas SIMET baseadas em sistema operacional Debian ou Ubuntu.
Arquivos de configuração#
O medidor SIMET obtém vários itens de configuração a partir de arquivos de texto UTF-8, com marcadores de fim-de-linha padrão UNIX (LF). Não devem ser utilizados marcadores de fim-de-linha no padrão do MS-DOS / Microsoft Windows (CR+LF).
Os arquivos de configuração do medidor SIMET são processados na ordem listada abaixo.
Arquivos lidos por último podem modificar itens de configuração definidos por arquivos lidos anteriormente e por isso a configuração padrão é lida primeiro:
/opt/simet/lib/simet/simet-ma.conf
Configuração padrão do motor de medição. Este arquivo não deve ser alterado. Ele somente é modificado quando necessário por uma nova versão do motor de medição, e é distribuído junto com o software.
/opt/simet/lib/simet/conf.d/
Pasta com vários arquivos de configuração, lidos em ordem definida pelo LOCALE “C”. É recomendado prefixar cada arquivo com um número de dois dígitos, garantindo a ordem em que serão processados. Os nomes dos arquivos devem terminar em “.conf”, ou serão ignorados.
Separar em arquivos diferentes as parametrizações comuns a todos os medidores de um mesmo fabricante, de uma mesma plataforma, de um mesmo modelo, e específicas para um exato equipamento.
/opt/simet/etc/simet/simet-ma.conf
Configurações específicas do equipamento, particularmente útil para itens de configuração que sejam ajustáveis via UI do medidor.
Formato dos arquivos#
Os arquivos de configuração contém um item de configuração por linha, no formato CHAVE=”VALOR”. Restrinja-se a chaves e valores válidos para shells POSIX.
Linhas iniciadas por “#” são comentários, utilize UTF-8 válido para evitar problemas.
Exemplo de um arquivo de configuração (inclua este arquivo em todas as Sondas SIMET que forem baseadas em Debian ou Ubuntu):
/opt/simet/lib/simet/conf.d/15-simetbox.conf
# SIMETBox profile / dedicated measurement probe
# MA family is "embedded", because its main purpose is to
# be a measurement agent, and the measurement engine can and
# will tune the entire system for measurements, if need be.
SIMET2_AGENT_FAMILY="embedded"
# Hostnames of SIMETBoxes are registered with the central system
# to help user support.
SIMET2_MAHOSTNAME="auto"
Variáveis de configuração#
SIMET2_FIRMWARE_VENDOR
Exemplo:: SIMET2_FIRMWARE_VENDOR=”Ficticia”.
Indica o responsável pela geração do firmware, e também por gerar novas versões de firmware com correções do motor de medição, e atualizações de segurança dos outros componentes.
Deve conter o nome do fabricante do equipamento, se o agente de medição SIMET foi embarcado no firmware original do fabricante [pelo fabricante]. Caso contrário, deve conter o nome do integrador que é responsável pelo firmware e suas atualizações.
SIMET2_DEVICE_MODEL
Exemplo:: SIMET2_DEVICE_MODEL=“Ficticia WRT-99BNG v3”
Deve conter o nome completo do equipamento e versão de hardware, incluir o nome do fabricante do equipamento. Pode incluir o model number, etc.
SIMET2_MAHOSTNAME
Exemplo:: SIMET2_MAHOSTNAME=”auto”
Define o hostname (opcional) a ser utilizado no registro do medidor SIMET. Particularmente útil no caso de agente de medição SIMET instalado em computador de uso geral. Neste caso, o recomendado é que seja identificado em qual computador foi instalado.
Em Sondas SIMET/SIMETBox costuma ser utilizado para identificar o local e enlace de Internet onde foi instalado o medidor.
-
“auto”: envia o hostname configurado no sistema operacional.
-
Vazio: não envia um hostname.
SIMET2_MADESCRIPTION
Exemplo:: SIMET2_MADESCRIPTION=”Medidor escola INEP12345678”
Define uma descrição (opcional) para o medidor, a ser utilizada no registro do medidor SIMET.
Útil para o suporte técnico ou para o dono do medidor, para informar detalhes sobre o medidor ou local de instalação.
SIMET2_AGENT_ENVNAME, SIMET2_AGENT_ENVVERSION
Em Linux, estes itens de configuração são definidos automaticamente utilizando o comando “lsb_release”, ou diretamente a partir das informações de release do OpenWRT.
ENVNAME deve conter o nome abreviado do sistema operacional (por exemplo: “Debian”, “Ubuntu”, “OpenWRT”, “Mint”).
ENVVERSION deve conter o nome completo com versão do sistema operacional (por exemplo: “Debian GNU/Linux 12 (bookworm)”).
Nota
Ajustar conforme orientado acima apenas quando o ajuste automático não estiver funcional na plataforma. Ao portar o medidor SIMET para outros sistemas operacionais, o ajuste automático desses itens de configuração deve ser implementado para o novo sistema operacional.
Reconhecer o ambiente via DMI#
Em plataformas onde o kernel Linux detecta e exporta via /sys/firmware/dmi a presença de uma tabela DMI1, o motor de medição irá (a menos que parametrizado em contrário) buscar por:
1. Nome do fabricante, e identificação do modelo:
- DMI Handle 0x0001, DMI type 1: “System Information”
- DMI Handle 0x0002, DMI type 2: “Base Board Information”
Busca pelos campos “Manufacturer”, e “Product Name” e que não contenham as strings “O.E.M”, “OEM”, “to be ”, “not ” (case-insensitive).
Caso o campo “Version” seja especificado, é utilizado como sufixo à identificação do modelo.
Alternativamente, definir o ítem de configuração “SIMET2_DEVICE_MODEL” conforme explicado na seção anterior.
2. Número de série ou UUID:
- DMI Handle 0x0001, DMI type 1: “System Information”
- DMI Handle 0x0002, DMI type 2: “Base Board Information”
Busca pelos campos “Serial Number” e “UUID”, e que não contenham as strings “O.E.M”, “OEM”, “to be ”, “not ” (case-insensitive).
Também serão descartados:
- serial number todo-zero, todo-espaços ou com menos que 6 caracteres
- UUIDs com todos os bits em “0” ou todos os bits em “1”.
Se ambos UUID e Serial Number forem definidos, a UUID é utilizada preferencialmente.
Atenção
Para todos os campos acima, só é buscado no DMI handle type 2 o campo que não puder ser satisfeito pelo DMI handle type 1.
Esta informação é utilizada para gerar a "chave SIMET" (“virtual label” no código fonte do medidor SIMET) do motor de medição, e não é transmitida para fora do equipamento.
A "chave SIMET" é obtida do UUID ou serial number através de uma transformação criptográfica (one-way hash) em esquema PBKDF2 ou similar.
Alternativamente, suprir o(s) executável(is) get_platform_simet_label e/ou get_platform_simet_secret descritos abaixo.
Estas informações são acessadas pelo motor de medição via software padrão “dmidecode”, ou diretamente em /sys/firmware/dmi, durante a inicialização do sistema ou instalação do motor de medição. Elas exigem permissão de superusuário e são mantidas em cache acessível pelo usuário não-privilegiado do motor de medição.
ATENÇÃO
O integrador e fabricante devem obrigatoriamente verificar se essas tabelas estão corretamente preenchidas. ja que é comum encontrar entradas com os dizeres “to be filled by O.E.M.”, por exemplo.
Alternativamente, o integrador ou fabricante pode acrescentar os scripts ou programas que informam ao motor de medição a informação correta, conforme descrito a seguir.
Caso as informações DMI estejam incorretas, ausentes, ou o integrador/fabricante prefira utilizar outras fontes para fornecer os parâmetros necessários, deverá fazê-lo através de scripts ou programas instalados em local específico, que o medidor detecta automaticamente e executa.
Reconhecer o ambiente via script#
O medidor SIMET utilizará programas executáveis (scripts ou compilados) instalados pelo integrador/fabricante ao detectar a existência destes.
Isto é feito para obter diversas informações da plataforma, exceto para aquelas que tenham sido definidas via item de configuração, conforme descrito anteriormente.
É necessário que estes scripts possuam permissão de execução para root e para o usuário não privilegiado do medidor (“nicbr-simet”).
1. Script Plataform Secret
/opt/simet/lib/simet/vendor/get_platform_simet_secret
/usr/lib/simet/vendor/get_platform_simet_secret
Deve estar presente caso um identificador único e permanente do dispositivo (não alterado mesmo em caso de atualização de firmware ou BIOS/UEFI) não possa ser corretamente obtido pelo medidor via tabelas DMI.
O programa/script deve retornar um identificador único (um segredo) que precisa estar armazenado em memória não volátil protegida do equipamento.
Uma vez gerado, este identificador não pode mais mudar mesmo no caso de atualização de firmware, recuperação de emergência do firmware/sistema operacional e reset de fábrica.
Pode ser gerado em fábrica, ou da primeira vez que o script/programa for executado: o que importa é que uma vez gerado, ele não mude.
Endereços MAC e derivações matemáticas do mesmo não podem ser utilizadas.
Esta informação é utilizada para gerar a “chave SIMET” (“virtual label” no código fonte) do medidor, e não é transmitida para fora do equipamento. A “chave SIMET” é obtida através de uma transformação criptográfica (one-way hash) em esquema PBKDF2 ou similar, para proteger o identificador único.
Para maiores detalhes, consulte o exemplo.
2. Script Plataform Label
/opt/simet/lib/simet/vendor/get_platform_simet_label
/usr/lib/simet/vendor/get_platform_simet_label
Deve estar presente apenas no caso onde o dispositivo possui uma etiqueta física, impressa e colada em seu exterior (“etiqueta SIMET”), onde consta o MAC do equipamento e a “chave SIMET”, que tenha sido gerada pelo fabricante e armazenada em área de configuração não-volátil da FLASH do equipamento.
Se a “chave SIMET” foi calculada pelo medidor SIMET, o programa / script get_platform_simet_label não deve estar presente, ou deve retornar exit status 1.
Apenas utilize esta funcionalidade após consultar a equipe SIMET do NIC.br.
Para maiores detalhes, consulte o exemplo.
3. Script Device Model
Atenção
Este programa não é suportado no OpenWRT. Neste, é necessário que o próprio sistema operacional esteja detectando corretamente o device_model.
Deve estar presente quando o modelo do equipamento não puder ser determinado a partir das tabelas de informação DMI.
Retorna, em stdout, uma só linha e separados por espaço: o nome do fabricante, modelo, e versão de hardware do equipamento. Deve retornar exit status zero em caso de sucesso, e não-zero em caso de falha. Envia mensagens de erro para stderr.
Ver a definição de SIMET2_DEVICE_MODEL nas Variáveis de Configuração para maiores detalhes e exemplos. Veja também o exemplo em código fonte, que é funcional em plataformas que retornem em /proc/cpuinfo uma linha “Model:” com seu fabricante e modelo.
4. Script MAC Address
Deve estar presente sempre que o equipamento possua um endereço MAC impresso em etiqueta.
O programa deve retornar, em stdout, uma única linha com o endereço MAC do dispositivo que está presente na etiqueta física do mesmo, e retornar exit status zero.
Caso a etiqueta contenha múltiplos endereços MAC, deve retornar o “visivelmente mais importante” (por exemplo, o primeiro deles, ou um que esteja em destaque por algum outro motivo).
Erros devem ser retornados em stderr, e em caso de erro o programa/script deve retornar exit status não-zero.
Atenção
Este programa não é suportado no OpenWRT. Neste, identifique na Device Tree o nodo que provê o MAC address impresso na etiqueta do dispositivo ou ajuste a parametrização do mesmo para que retorne a informação correta na API, conforme descrito em Script MAC Address.
É necessário que o medidor SIMET possa, no OpenWRT, obter o MAC impresso na etiqueta através da sequência de comandos shell (conforme documentado no hiperlink acima para a documentação do OpenWRT):
Na impossibilidade, entre em contato com a equipe SIMET do NIC.br.
Relógio de tempo real#
Antes de iniciar os serviços do medidor SIMET, o relógio do sistema deve ser ajustado pelo sistema operacional para a data e horas corretas.
É importante observar que um erro muito grande no relógio de sistema impede o correto funcionamento das camadas https e DNSSEC do sistema (inclusive do medidor).
É recomendado (mas não é exigido) que sondas SIMET possuam um RTC2 com bateria, que mantenha a data e hora aproximadamente correta mesmo quando o equipamento for desligado.
Nota
É extremamente recomendado que o equipamento, caso não possua RTC com bateria, utilize o sistema de arquivos para uma aproximação de tempo inicial, seguido de ajuste SNTP3 ou HTP4 assim que obtiver conexão com a Internet, e utilizar NTS5 ou NTP para ajuste continuado do relógio de sistema.
Sondas SIMET devem necessariamente utilizar NTP ou NTS para ajuste contínuo do relógio (recomendamos que utilize servidores do projeto NTP.br).
Admite-se o uso de outras fontes de temporização ainda melhores (GPS, PPTP, etc).
-
2- Real Time Clock ↩
-
3- o Simple Network Time Protocol (SNTP) ajusta o relógio do sistema apenas uma vez contactando um servidor NTP. Precisa ser executado periodicamente para compensar erros acumulados pelo relógio do sistema. Não é capaz de ajustar a frequência do relógio do sistema. ↩
-
4- Http Time Protocol. Realiza um acesso a servidor(es) http e utiliza a timestamp retornada pelo servidor no cabeçalho http “Date”. Deve ser utilizado apenas se SNTP for impossível. ↩
-
5- NTS: “Secure NTP”. Mais informações. ↩