Commit b82b461f authored by André Guimarães Coelho's avatar André Guimarães Coelho
Browse files

[OPENBUS-2209] Correções e melhorias nos manuais (de introdução e de instalação)

- Correções e melhorias nos manuais, glossário e bibliografia.



git-svn-id: https://subversion.tecgraf.puc-rio.br/engdist/openbus/core/branches/02_00_00@138849 ae0415b3-e90b-0410-900d-d0be9363c56b
parent 08d6b0b3
......@@ -115,6 +115,7 @@ Para outras plataformas geramos pacotes sob demanda, exemplos:
\item Solaris 10 release 8/07 SPARC 32 bits (SunOS510)
\end{itemize}
Os exemplos deste documento utilizam comandos do Bash shell (interpretador de linguagem de comandos)~\cite{web:bash}.
Para executar o barramento deve-se seguir o seguinte procedimento:
\begin{enumerate}
......@@ -149,13 +150,26 @@ $OPENBUS_HOME/bin/busservices --help
-out <nome do par de chaves>.crt -outform DER
\end{verbatim}
\item Executar o barramento passando as configurações desejadas. Como por exemplo, o par de chaves do barramento.
\item Configurar o validador (ver próxima seção) e executar o barramento (binário \emph{busservices}), passando as configurações da chave privada e do validador a serem utilizados, as quais são obrigatórias para execução do OpenBus.
\end{enumerate}
Maiores informações sobre como utilizar a configuração do \emph{busservices} podem ser encontradas no manual de referência~\cite{ob2.0core}.
\section{Configuração do validador LDAP}
\section{Validadores}
\subsection{Para que servem?}
São responsáveis por autenticar o sistema/usuário que se conecta ao barramento.
Atualmente pode-se utilizar 2 tipos de validadores no OpenBus: validadores LDAP ou validadores personalizados.
\begin{itemize}
\item Validadores LDAP - usam 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~\cite{web:rfc4510,wiki:LDAP} para a autenticação de usuários.
\item Validadores personalizados - utilizam funções escritas em Lua para verificar a autenticidade dos usuários.
\end{itemize}
\subsection{Validadores LDAP}
O validador LDAP, disponibilizado em \texttt{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 \emph{busservices} através do parâmetro ``-configs''. A seguir apresentamos quais são as propriedades, seus significados e possíveis valores:
\begin{description}
......@@ -167,7 +181,7 @@ ldap_servers = {
}
\end{verbatim}
\item[ldap\_patterns] indica uma lista de padrões de formação de nomes que serão usados na autenticação LDAP. Atualmente só há suporte para o padrão \texttt{\%U}, e o validador irá substituir esse padrão pelo nome do usuário fornecido no ato do login. No exemplo abaixo apresentamos dois padrões, o primeiro é útil para autenticação em servidores Microsoft Active Directory (que utilizam UPN \cite{web:upn}) e o segundo é útil para autenticação em servidores OpenLDAP (que utilizam DN \cite{web:dn,web:rfc4514}). Exemplo:
\item[ldap\_patterns] indica uma lista de padrões de formação de nomes que serão usados na autenticação LDAP. Atualmente só há suporte para o padrão \texttt{\%U}, e o validador irá substituir esse padrão pelo nome do usuário fornecido no ato do login. No exemplo abaixo apresentamos dois padrões, o primeiro é útil para autenticação em servidores Microsoft Active Directory (que utilizam UPN~\cite{web:upn}) e o segundo é útil para autenticação em servidores OpenLDAP (que utilizam DN~\cite{web:dn,web:rfc4514}). Exemplo:
\begin{verbatim}
ldap_patterns = {
"%U@project.mycompany.com",
......@@ -181,9 +195,10 @@ ldap_timeout = 10
\end{verbatim}
\end{description}
\section{Criação de um validador personalizado}
Um validador precisa ser um módulo Lua\cite{web:luamodule} que deve retornar uma função que recebe como parâmetro uma tabela de configurações do barramento e retorna uma função \texttt{validator}. A função \texttt{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:
\subsection{Validadores personalizados}\label{subsec:valpersonalizados}
Um validador personalizado precisa ser um módulo Lua~\cite{web:luamodule} que deve retornar uma função que recebe como parâmetro uma tabela de configurações do barramento e retorna uma função \texttt{validator}. A função \texttt{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:
\begin{verbatim}
local function validator(name, password)
if name == password then
......@@ -194,7 +209,10 @@ end
return function(configs) return validator end
\end{verbatim}
Para utilizar um validador como esse, pode ser necessário a configuração das variáveis de ambiente LUA\_PATH e LUA\_CPATH. Caso não esteja familiarizado, consulte o manual da linguagem Lua\cite{web:luamodule}.
Para ver um exemplo de como configurar um validador personalizado, consulte a seção FAQ~\ref{sec:faq}.
\section{Configurações opcionais para administradores do servidor}
......@@ -236,7 +254,7 @@ Um exemplo de agendamento no \emph{cron} para utilizar o \emph{bus-check-running
\subsection{Rotacionamento de logs}
Por padrão, o barramento imprime logs em tela. É \textbf{fortemente recomendado} configurar o barramento para salvar esses logs em arquivos, conforme documentado em\cite{ob2.0core}. Por isso, recomendamos uma estratégia para rotacionar os arquivos de log.
Por padrão, o barramento imprime logs em tela. É \textbf{fortemente recomendado} configurar o barramento para salvar esses logs em arquivos, conforme documentado em~\cite{ob2.0core}. Por isso, recomendamos uma estratégia para rotacionar os arquivos de log.
O comando \textbf{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.
......@@ -280,7 +298,7 @@ Os significados das op
\item O parâmetro \texttt{-P} será adicionado pelo próprio logadm após a primeira execução, ele é responsável por controlar a próxima data que o rotacionamento ocorrerá.
\end{enumerate}
\section{FAQ}
\section{FAQ}\label{sec:faq}
\subsection{Não lembro a sintaxe do crontab. Qual é ela mesmo?}
......@@ -362,6 +380,16 @@ Nas plataformas Solaris a forma mais simples
Após esse procedimento basta ter a pasta \$HOME/bin no PATH.
\subsection{Como configuro um validador personalizado?}
Um exemplo simples de configuração de um validador personalizado, seria criar um código como o apresentado em \ref{subsec:valpersonalizados}, 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:
\begin{verbatim}
export LUA_PATH+=";<caminho onde está o validador>/?.lua"
\end{verbatim}
Para maiores informações, consulte o manual da linguagem Lua~\cite{web:luamodule}.
\subsection{Ainda estou com dúvidas. Como entro em contato?}
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.
......
......@@ -37,7 +37,7 @@ dada entidade no barramento.
\item [Controle de Acesso] Serve como ponto de entrada do barramento, sendo responsável por autenticar, renovar e gerenciar os logins de serviços e aplicações ao barramento.
\item [\corba{}] \emph{Common Object Request Broker Architecture}. Espeficiação de um padrão de ORB sobre a qual o OpenBus é definido e implementado.
\item [\corba{}] \emph{Common Object Request Broker Architecture}. Especificação de um padrão de ORB sobre a qual o OpenBus é definido e implementado.
O \openbus{} pode ser visto como uma extensão do padrão \corba{}.
\end{description}
......@@ -69,6 +69,8 @@ Entidades podem ser usu
\item [Lease] Período de tempo pelo qual um login no barramento permanecerá válido sem necessidade de renovação.
Contudo, um login pode ser invalidado explicitamente por um administrador antes do tempo de lease.
\item [LDAP] \emph{Lightweight Directory Access Protocol}. É um protocolo de Internet para acessar serviços de diretório distribuídos. É comumente usado para autenticação em redes corporativas.
\item [Login] Representa uma autenticação de uma entidade junto ao barramento para poder acessá-lo.
\item [Logout] Processo no qual o criador de um login o invalida, fazendo com que esse login não possa mais ser usado para acessar o barramento.
......@@ -116,3 +118,9 @@ Todos servi
\item [Serviços Extras] Serviços que acrescentam funcionalidades para auxiliar a integração entre serviços e aplicações, mas que não são parte do núcleo do barramento.
\end{description}
\subsection*{V}
\begin{description}
\item [Validadores LDAP] São utilizados para autenticar usuários em serviços de diretório que utilizam o protocolo LDAP.
\end{description}
......@@ -51,6 +51,8 @@
% This is now the recommended way for checking for PDFLaTeX:
\usepackage{ifpdf}
\usepackage{listings}
%% Redefines the label 'Listing' for ..
\def\lstlistingname{Código}
\codestyle{colorful}
......@@ -164,7 +166,7 @@ Entraremos em detalhes sobre as partes principais do \openbus{} nas subse
\begin{figure}
\centering
\includegraphics[width=\textwidth]{figs/architecture.png}
\includegraphics[width=\textwidth]{figs/architecture}
\caption{Arquitetura do \openbus{}}
\label{fig:architecture}
\end{figure}
......@@ -327,7 +329,7 @@ Valor padr
Valor padrão é ``openbus.key"
\item [-leasetime] Tempo em segundos de lease dos logins de acesso.\\
Valor padrão é 180 segundos.
Valor padrão é 1800 segundos.
\item [-expirationgap] Tempo em segundos que os logins ficam válidos após o lease.\\
Valor padrão é 10 segundos.
......@@ -394,7 +396,7 @@ Existem os conceitos de:
Entidades podem ou não ser cadastradas no barramento, mas apenas entidades cadastradas podem ser autorizadas a ofertar serviços.
\item[Certificado] Chave pública que pode ser usada para autenticar uma
dada entidade no barramento.
dada entidade no barramento. Ver seção sobre geração de chaves para informações sobre como gerar as chaves pública e privada.
É possível adicionar certificados para entidades não cadastradas no barramento.
\item[Interface] Definição de uma interface IDL de um serviço que pode ser ofertado no barramento.
......@@ -408,16 +410,12 @@ Para utilizar a ferramenta, deve-se executar:
busadmin [opções] --login=<usuário> <comando>
\end{verbatim}
Para adicionar e remover categorias, entidades, certificados, interfaces e autorizações, aconselhamos que se defina um arquivo de script \lua{} com o formato especificado no código~\ref{lst:openbus.adm}, porque ele serve de entrada para os comandos ``script'' e ``undo-script'' da ferramenta \emph{busadmin}, que executa ou desfaz a execução do lote de comandos especificados pelo arquivo de script.
Para adicionar e remover categorias, entidades, certificados, interfaces e autorizações, aconselhamos que se defina um arquivo de script \lua{} com o formato especificado no código~\ref{lst:openbus.adm}. Ele serve de entrada para os comandos ``script'' e ``undo-script'' da ferramenta \emph{busadmin}, que, respectivamente, executa e desfaz a execução do lote de comandos especificados pelo arquivo de script.
\begin{htmlonly}
\codeinput{openbus.adm}{Exemplo de script para a ferramenta \emph{busadmin}:}
\end{htmlonly}
\begin{latexonly}
\inputlisting[language=lua]{openbus.adm}{Exemplo de script para a ferramenta \emph{busadmin}.}
\end{latexonly}
O \emph{busadmin} também permite realizar esses cadastros e descadastros manualmente, além de realizar consultas e outras atividades de gerência do barramento.
A listagem completa dos comandos disponíveis é apresentada a seguir:
......@@ -442,6 +440,7 @@ A listagem completa dos comandos dispon
\item[\texttt{--}certificate=\textless arquivo\textgreater] Informa a chave privada para realizar a autenticação por certificado, ao invés de ser por senha.
O padrão é realizar a autenticação por senha, onde a ferramenta pergunta a senha antes de executar o comando.
\end{description}
\item \textbf{Controle de Categoria:}
......@@ -577,9 +576,48 @@ O padr
\end{itemize}
\begin{latexonly}
\codeplacement{!hb}
\inputlisting[language=lua]{openbus.adm}{Exemplo de script para a ferramenta \emph{busadmin}.}
\end{latexonly}
\subsection{Geração de chaves}
Dentro do pacote de distribuição do OpenBus, está incluso o binário do OpenSSL, que permite gerar chaves privada e pública.
Antes de utilizar o binário, é necessário executar os seguintes comandos (estamos utilizando comandos do Bash shell~\cite{web:bash} no exemplo abaixo):
\begin{verbatim}
#este comando é apenas para facilitar a legibilidade do código abaixo, sendo opcional
export OPENBUS_HOME=<local de extracao do pacote>
export LD_LIBRARY_PATH="${OPENBUS_HOME}/lib:${LD_LIBRARY_PATH}"
# caso seja MacOS é preciso também:
export DYLD_LIBRARY_PATH="${OPENBUS_HOME}/lib:${DYLD_LIBRARY_PATH}"
\end{verbatim}
Para gerar a chave privada, utilize os seguintes comandos:
\begin{verbatim}
${OPENBUS_HOME}/bin/openssl genrsa -out tmp_openssl.key 2048
${OPENBUS_HOME}/bin/openssl pkcs8 -topk8 -nocrypt \
-in tmp_openssl.key -out <nome do par de chaves>.key -outform DER
rm -f tmp_openssl.key
\end{verbatim}
Para gerar o certificado, utilize o seguinte código:
\begin{verbatim}
${OPENBUS_HOME}/bin/openssl req -config $OPENSSL_HOME/openssl.cnf -new -x509 \
-key <nome do par de chaves>.key -keyform DER \
-out <nome do par de chaves>.crt -outform DER
\end{verbatim}
\subsection{Desenvolvedores de Sistemas Integrados}
Como informado na seção~\ref{sec:barramento}, oferecemos uma biblioteca de acesso, que implementa o protocolo e exporta uma API de programação, que oferece alguns facilitadores e auxilia a interação com o barramento.
Como informado na seção~\ref{sec:barramento}, oferecemos uma biblioteca de acesso, que implementa o protocolo e exporta uma API de programação, a qual oferece alguns facilitadores e auxilia a interação com o barramento.
Para maiores informações, consulte o manual de uso da biblioteca de acesso~(seção \ref{sec:library}).
......
......@@ -142,3 +142,28 @@ year = {2008}}
Url = {http://www.ietf.org/rfc/rfc4514.txt},
howpublished = "\url{http://www.ietf.org/rfc/rfc4514.txt}",
year = {2012}}
@misc{web:rfc4510,
Author = {{OpenLDAP Foundation}},
Lastchecked = {6 March 2013},
Title = {{RFC} 4510 - Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map},
Url = {http://www.ietf.org/rfc/rfc4510.txt},
howpublished = "\url{http://www.ietf.org/rfc/rfc4510.txt}",
year = {2013}}
@misc{wiki:LDAP,
author = "Wikipedia",
title = "Lightweight Directory Access Protocol --- {W}ikipedia{,} The Free Encyclopedia",
year = "2012",
url = "http://en.wikipedia.org/w/index.php?title=Lightweight_Directory_Access_Protocol&oldid=541744076",
note = "[Online; accessed 06-March-2012]"
}
@misc{web:bash,
Author = {{GNU}},
Lastchecked = {12 March 2013},
Title = {Bash Reference Manual},
Url = {http://www.gnu.org/software/bash/manual/bashref.html},
howpublished = "\url{http://www.gnu.org/software/bash/manual/bashref.html}",
year = {2010}}
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment