Tecgraf
15. Fevereiro 2018
Este documento visa informar apenas o procedimento necessário para instalar um barramento OPENBUS [11] da versão 2.1.0. Caso tenha interesse em entender melhor o que é um barramento OPENBUS, consulte o documento de visão geral [14].
O primeiro passo para instalar o barramento deve ser descompactar o pacote do barramento da plataforma desejada. Os pacotes estão disponibilizados no site oficial do projeto: http://www.tecgraf.puc-rio.br/openbus.
As plataformas oficialmente suportadas são:
Para outras plataformas geramos pacotes sob demanda, exemplos:
Os exemplos deste documento utilizam comandos do Bash shell (interpretador de linguagem de comandos) [1]. Para executar o barramento deve-se seguir o seguinte procedimento:
export OPENBUS_HOME=<local de extracao do pacote>
$OPENBUS_HOME/bin/busservices --help
# Para gerar a chave privada, utilize os seguintes comandos:
openssl genrsa -out tmp_openssl.key 2048
openssl pkcs8 -topk8 -nocrypt \
-in tmp_openssl.key -out <nome do par de chaves>.key -outform DER
rm -f tmp_openssl.key
# Para gerar o certificado:
openssl req -days <validade do certificado em dias> -new -x509 \
-key <nome do par de chaves>.key -keyform DER \
-out <nome do par de chaves>.crt -outform DER
Os validadores representam o conceito de um módulo Lua [2] responsável por verificar se o par usuário e senha fornecido em uma tentativa de autenticação junto ao barramento é válido. Atualmente pode-se utilizar 2 tipos de validadores no OpenBus: validadores de senha e validadores de autenticação externa.
Um validador de senha precisa ser um módulo Lua [2] que deve retornar uma função que recebe como parâmetro uma tabela de configurações do barramento e retorna uma função validator. A função validator recebe como primeiro parâmetro o nome de usuário e, como segundo, a senha. Caso o par usuário/senha seja válido, deve-se retornar verdadeiro, caso contrário, falso. Um exemplo de validador que verifica se o nome do usuário é igual à senha é dado a seguir:
-- this is the validator function
local function validator(name, password)
if name == password then
return true
end
end
-- returning the factory to validation function
return function(configs) return validator end
Então, sempre que este módulo for carregado, ele retornará a fábrica de função de validação.
-- dummy usage example of this validation module local factory = require "example.of.validator" local validator = factory() local isValid = validator(login, password)
Podemos implementar os validadores tão simples ou seguros como desejarmos. É importante frisar que o validador personalizado precisa estar no LUA_PATH para que seja encontrado pelo executável busservices. Um exemplo de como configurar o LUA_PATH para um validador personalizado é apresentado no FAQ (seção 7).
Junto ao pacote do OPENBUS é fornecido um validador pré-definido para validação via LDAP. Esse validador usa as informações contidas em um serviço de diretórios LDAP para autenticar o acesso de usuários ao barramento. Em ambientes corporativos, é comum a administração da rede utilizar servidores LDAP [10,15] para a autenticação de usuários.
Disponibilizado em openbus.core.services.passwordvalidator.LDAP, tem suporte a servidores Microsoft Active Directory e OpenLDAP. As configurações do validador precisam estar no arquivo de configuração que é informado ao busservices através do parâmetro -configs. A seguir apresentamos quais são as propriedades, seus significados e possíveis valores:
ldap_servers = {
"ldaps://server.mycompany.com",
"ldap://otherserver.mycompany.com:389",
}
ldap_patterns = {
"%U@project.mycompany.com",
"cn=%U,ou=users,ou=groups,dc=company",
}
ldap_timeout = 10
ldap_cleartext = true
ldap_iorpath = "/tmp/openbus/ldapthread.ior"
Um validador de autenticação externa é implementado de forma similar a um validador de senha, descrito na seção 3.2. Contudo, a função validator do validador de autenticação externa recebe os seguintes parâmetros:
O barramento e os serviços núcleo são distribuídos em um mesmo programa, o busservices. Logo, para disparar o barramento, basta executar o programa passando as suas configurações por linha de comando ou por arquivo de configuração. Se uma configuração não for explicitada, será utilizado o seu valor padrão.
As opções de configuração são:
<domain>:<package> onde <domain> é um nome do domínio de autenticação do validador e <package> é o nome do pacote Lua que implementa o validador de senhas.
<domain>: é opcional.
Caso seja omitida, o domínio adotado para o validador é a string vazia.
<domain>:<package> onde <domain> é um nome do domínio de autenticação do validador e <package> é o nome do pacote Lua que implementa o validador de autenticação externa.
<domain>: é opcional.
Caso seja omitida, o domínio adotado para o validador é a string vazia.
As opções admin, validator, tokenvalidator e alternateaddr podem aparecer mais de uma vez para definir multiplos valores. (ao contrário do OpenBus 2.0, isso também é válido para definições no arquivo de configuração.) O código 1 apresenta um exemplo de arquivo do configuração.
src/openbus.cfgExemplo de arquivo de configuração: Existem duas formas de se definir o arquivo de configuração que o programa irá utilizar: utilizando a opção config por linha de comando, ou definindo um valor para a variável de ambiente OPENBUS_CONFIG. Quando a variável de ambiente OPENBUS_CONFIG não é definida, o arquivo openbus.cfg no diretório corrente é usado por default como arquivo de configuração. Porém, as opções passadas por linha de comando têm prioridade sobre as opções definidas no arquivo de configuração.
Através da opção validator informa-se o módulo do validador de senhas que será utilizado pelo barramento. Disponibilizamos em openbus.core.services.passwordvalidator.LDAP um validador LDAP, que precisa ser configurado com a lista de servidores utilizados na autenticação. Para maiores informações sobre como configurar o validador LDAP, consulte a seção 3.2.1.
Através da opção tokenvalidator pode-se informar o módulo de um validador de autenticação externa que será utilizado pelo barramento.
Também é possível desabilitar o suporte de compatibilidade com a versão anterior através da opção nolegacy. Ao ativar essa opção, o barramento deixa de permitir que entidades se autentiquem no barramento utilizando as bibliotecas de acesso de versão 2.0.x.
A ferramenta busadmin facilita a gerentes do barramento a realização de atividades de governança (administração) sobre o barramento. Para informações sobre como utilizá-la, consulte [13]. Caso já esteja familiarizado com a versão 2.0.x da ferramenta, consulte também [12].
No pacote do barramento existem facilitadores adicionais para apoiar tarefas diárias comuns ao administrador do servidor como auditoria das chamadas recebidas no barramento, inicialização no boot do servidor, monitoramento periódico do processo e rotacionamento de logs.
A partir da versão 2.1.0.2, o executável busservices passou a ter uma opção (-enableaudit) para coletar dados das chamadas recebidas e enviá-los para um serviço HTTP RESTful externo. O envio é realizado por um cliente HTTP embutido no processo do busservices e conhecido como agente de auditoria. O agente de auditoria envia um POST HTTP com a informação de cada requisição coletada em formato JSON[3], conforme a seguinte estrutura:
{
solutionCode : "string",
environment : "string",
id : "string",
timestamp : "yyyy-mm-dd hh:mm:ss.SSS"
actionName : "string",
userName : "string",
loginId : "string",
interfaceName : "string",
openbusProtocol : "string",
ipOrigin : "WWW.XXX.YYY.ZZZ:PPPP",
input : "string",
duration : "ss.SSSS",
output : "string",
resultCode : "string",
}
Os dados coletados na auditoria são detalhados a seguir. Caso não seja possível coletar algum deles, o dado será preenchido com null (ou <unknown> no caso da entidade e login).
Entre os campos acima, apenas environment e solutionCode podem ser alterados através da configuração dos parâmetros -auditapplication e -auditenvironment do busservices, respectivamente.
Recomenda-se usar o -auditapplication como um identificador da tecnologia, por exemplo OPENBUS, e o -auditenvironment como um identificador da instalação.
O serviço de auditoria, por sua vez, não é fornecido no pacote do barramento. Um exemplo de código baseado em Node.JS[7] que executa uma aplicação web para efeitos de teste da auditoria é dado a seguir. Este exemplo utiliza o endereço http://localhost:8080 para publicar eventos sem autenticação e http://localhost:8080/protected para experimentar uso de autenticação HTTP (será necessário usar os parâmetros -auditendpoint e -auditcredentials no busservices).
const express = require('express')
const app = express()
var basicAuth = require('basic-auth');
var auth = function (req, res, next) {
function unauthorized(res) {
res.set('WWW-Authenticate', 'Basic realm=Authorization Required');
return res.sendStatus(401);
};
var user = basicAuth(req);
if (!user || !user.name || !user.pass) {
console.log(req.url + " access denied. missing authentication header");
return unauthorized(res);
};
if (user.name === 'fulano' && user.pass === 'silva') {
console.log(req.url + " access granted for user " + user.name);
return next();
} else {
console.log(req.url + " access denied. invalid user credentials user " + user.name);
return unauthorized(res);
};
};
var bodyParser = require("body-parser");
app.use(bodyParser.urlencoded({extended:false}));
app.use(bodyParser.json());
const port = 8080
app.post('/protected', auth, (req, res) => {
console.log('Received a protected event ' + req.url)
console.log(req.body);
res.end('');
})
app.post('/', (req, res) => {
console.log('Received a public event ' + req.url)
console.log(req.body);
res.end('')
})
app.listen(port, () => console.log('Audit service app listening on port '+port))
O pacote de instalação do barramento acompanha o script de inicialização businit que serve para iniciar e parar o barramento, semelhante aos scripts do /etc/init.d em servidores Unix.
Recomendamos que o administrador coloque o script businit em /etc/init.d/openbus (ou outro lugar semelhante em seu sistema operacional) e faça o link simbólico apropriado para cada runlevel. É possível editar o script businit para redefinir o local da instalação do barramento (variável INSTALL_DIR), de modo que o script possa encontrar o executável do busservices. Alternativamente, é possível também definir a variável de ambiente OPENBUS_HOME para indicar o local de instalação do barramento para os scripts businit e buscheck (veja a seção seguinte).
Além disso, por padrão, este script carrega configurações adicionais definidas no arquivo /etc/default/openbus, ou ainda no arquivo config/openbus.rc do diretório de instalação do barramento. Num desses arquivos podem ser definidas configurações adicionais tais como o nome do arquivo a ser criado para armazenar o PID do processo do busservices disparado (variável PIDFILE), o arquivo de log do barramento (variável OUTFILE), ou ainda o mail de notificação de reinícios (variável EMAIL).
É fortemente recomendado que o administrador do sistema configure o barramento para utilizar um arquivo de configuração. Nesse caso, o administrador precisa decidir onde colocar esse arquivo de configuração. Há duas formas de fazer isso utilizando os arquivos /etc/default/openbus ou config/openbus.rc:
export OPENBUS_CONFIG=/etc/openbus.cfg
PARAMS=-configs /etc/openbus.cfg
O pacote de instalação do barramento acompanha o script de monitoramento buscheck que verifica se o barramento está executando e, caso não esteja, inicia o barramento utilizando o script businit.
O script buscheck foi criado para ser utilizado em conjunto com o agendador de tarefas do sistema (comando cron no Unix). Assim como o script businit, o script buscheck também:
Como o script buscheck depende do script businit, caso o administrador decida colocar o businit em um outro local, é importante editar o script buscheck de acordo (variável OPENBUS_INIT).
Um exemplo de agendamento no cron para utilizar o buscheck é dado a seguir, neste exemplo consideramos que o barramento está instalado em /opt/openbus:
*/10 * * * * env OPENBUS_HOME=/opt/openbus /opt/openbus/bin/buscheck
O script businit desvia toda saída do barramento para um arquivo (veja variável OUTFILE no arquivo de configurações adicionais). É fortemente recomendado manter esses arquivos de saída para identificar problemas no uso do barramento. Por isso, recomendamos uma estratégia para rotacionar esses arquivos de saída.
O comando logrotate é um utilitário para simplificar a administração de arquivos de logs bem comum na maioria das instalações Linux e Solaris. O logrotate permite a rotação automática, a compressão dos logs antigos, a remoção de logs muito velhos e mesmo o envio de emails contendo os arquivos de logs.
Para rotacionar os logs do barramento, basta configurar o logrotate com as linhas a seguir. Neste exemplo consideramos que o barramento salva o log em /var/log/openbus.log:
/var/log/openbus.log {
weekly
compress
copytruncate
rotate 4
}
Os significados das opções recomendadas acima são dados a seguir:
O logadm é muito parecido com o logrotate. Para a rotação dos logs, nós iremos utilizar o crontab e o logadm. Caso não seja o root da máquina, você deve utilizar o parâmetro -f para informar um arquivo de configuração. Esse arquivo irá conter todos os logs que você deseja rotacionar. Abaixo temos um exemplo de como configurar o logadmin para rotacionar os logs do barramento.
00 05 * * * /usr/sbin/logadm -f /etc/openbus-logadm.conf
/var/log/openbus.log -C 5 -P 'Mon Jul 26 20:13:01 2010' -c -p 7d -z 0
Os significados das opções recomendadas acima são dados a seguir:
.---------------- minuto (0 - 59) | .------------- hora (0 - 23) | | .---------- dia do mês (1 - 31) | | | .------- mês (1 - 12) | | | | .---- dia da semana (0 - 6) (Domingo=0 ou 7) | | | | | * * * * * comando a ser executado e suas opções
Para adicionar um novo agendamento pode-se usar o arquivo global /etc/crontab (caso seja root) ou editar a tabela específica do usuário (todo usuário pode usar o cronpara rodar tarefas periódicas). O comando é:
crontab -e
Um arquivo com os agendamentos já existentes será aberto e será possível adicionar conforme informado anteriormente. Se o arquivo está vazio é porque o usuário do sistema não tem nenhum agendamento ainda.
A maioria das instalações Linux recentes já dispõem do diretório /etc/logrotate.d. Nesses casos, basta criar um arquivo chamado openbus (pode ser outro nome de sua preferência) e salvar as configurações acima nele.
É importante que o administrador leia as páginas de manual do logrotate (man logrotate), pois podem haver diferenças na configuração para versões antigas desse utilitário. Uma das situações comuns é não haver suporte ao diretório /etc/logrotate.d. Nesses casos, basta adicionar as configurações acima no arquivo /etc/logrotate.conf.
Não é necessário nenhuma permissão especial, basta o proprietário ser root e ter leitura para qualquer usuário (pode haver plataformas onde o logrotate execute como outro usuário que não o root).
No mesmo diretório dos arquivos originais.
Não é preciso. Normalmente o logrotate é cadastrado como uma tarefa diária no cron. Mas isso não impede de que o administrador execute tal comando passando o parâmetro force para obrigar o primeiro rotacionamento. Isso é indicado principalmente logo após a configuração inicial.
O logrotate não é um daemon, portanto não se mantém em execução. Normalmente, o logrotate é executado através do agendamento do cron. Caso não haja cron disponível em uma dada plataforma, então nesse caso será sim importante executar o comando do logrotate na inicialização da máquina.
O logrotate pode ser usado por usuários desprivilegiados (aqueles que não possuem acesso de root). Contudo, é muito comum que esses usuários ainda queiram rotacionar periodicamente seus arquivos de log. Nessa situação, recomendamos que o usuário adicione regras no agendador de tarefas do Unix (cron) para que o comando do logrotate seja chamado (ao menos) diariamente.
Para usuários desprivilegiados é importante usar alguns parâmetros do logrotate como o state. Esse parâmetro indica qual arquivo de estados será usado. O logrotate usa tal arquivo de estado para registrar a data da última rotação.
Segue um exemplo de agendamento do cron para executar o logrotate diariamente às 12:00 horas para o barramento instalado em /opt/openbus:
0 12 * * * /usr/sbin/logrotate --state /opt/openbus/logrotate.status /etc/openbus-logrotate.conf
É importante notar que o arquivo logrotate.status contendo o último estado da rotação foi mantido no diretório da instalação do barramento.
Nas plataformas Solaris a forma mais simples é baixar o pacote binário a partir do SunFreeware e usar diretamente da pasta do usuário. Um exemplo é dado a seguir:
wget -c ftp://ftp.sunfreeware.com/pub/freeware/sparc/10/logrotate-3.7.6-sol10-sparc-local.gz gunzip logrotate-3.7.6-sol10-sparc-local.gz mkdir /tmp/install pkgtrans logrotate-3.7.6-sol10-sparc-local /tmp/install
ls -l /tmp/install/SMClogr/reloc/
drwxr-xr-x 3 openbus tecgraf 512 Apr 12 15:24 doc
drwxr-xr-x 3 openbus tecgraf 512 Apr 12 15:24 man
drwxr-xr-x 2 openbus tecgraf 512 Apr 12 15:24 sbin
cp /tmp/install/SMClogr/reloc/sbin/logrotate $HOME/bin
Após esse procedimento basta ter a pasta $HOME/bin no PATH.
Um exemplo simples de configuração de um validador de senha seria criar um código como o apresentado em 3.2, e salvar o código em um arquivo com a extensão .lua. Depois, adicione o caminho onde foi salvo o arquivo à variável de ambiente LUA_PATH, da seguinte forma:
export LUA_PATH+=";<caminho onde está o validador>/?.lua"
Para maiores informações, consulte o manual da linguagem Lua [2].
Disponibilizamos uma lista pública de discussão com o intuito de reconhecer os usuários da nossa tecnologia, bem como receber sugestões e críticas que contribuam para a evolução do nosso projeto.
Maiores informações sobre a nossa lista de discussão veja http://listas.tecgraf.puc-rio.br/mailman/listinfo/openbus-users.