Tecgraf
24. Janeiro 2017
Este documento visa informar apenas o procedimento necessário para instalar um barramento OPENBUS [7] da versão 2.0.0. Caso tenha interesse de entender melhor o que é um barramento OPENBUS, consulte o seu manual de referência [8].
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
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
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
Maiores informações sobre como utilizar a configuração do busservices podem ser encontradas no manual de referência [8].
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 LDAP ou validadores personalizados.
O validador LDAP, 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 personalizado 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 5).
No pacote de instalação do barramento existem scripts que auxiliam algumas tarefas diárias comuns ao administrador da máquina onde o barramento está instalado. Esses scripts estão localizados na pasta bin e são eles:
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 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 precisa ser alterado para indicar o local de instalação do barramento(variável INSTALL_DIR). Também como o script businit, o script buscheck também carrega configurações do arquivo /etc/default/openbus, ou do arquivo config/openbus.rc do diretório de instalação do barramento.
Como o script depende do script businit, caso o administrador decida colocar o businit em um local particular, é 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-2.0:
*/10 * * * * env OPENBUS_HOME=/opt/openbus-2.0 /opt/openbus-2.0/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-2.0:
0 12 * * * /usr/sbin/logrotate --state /opt/openbus-2.0/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 personalizado, seria criar um código como o apresentado em 3.3, 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.