diff --git a/docs/apoio.rst.in b/docs/apoio.rst.in new file mode 100644 index 0000000..22308b3 --- /dev/null +++ b/docs/apoio.rst.in @@ -0,0 +1,66 @@ +Documentação de Apoio +===================== +.. _referencia: + +Gerar Chave SSH +--------------- +Antes de gerar a chave SSH, verifique se o seu sistema já não possui uma chave:: + + $ cat ~/.ssh/id_rsa.pub + +Se o comando acima retornar uma grande string que inicia com ``ssh-rsa`` ou ``ssh-dsa``, você já possui uma chave e, portanto, pode pular essa parte do guia. + +Para gerar a chave, apenas abra o terminal e digite o comando:: + + $ ssh-keygen -t rsa -C "seu_email" + +O comando acima irá perguntar em que arquivo e diretório você deseja armazenar sua chave, você pode apenas apertar ``Enter`` para usar o valor padrão. Também será perguntado se você deseja proteger sua chave com uma senha. A senha não é obrigatória, você pode ignorar essa configuraçao apenas apertando ``Enter``. Vale lembrar que essa senha não pode ser alterada posteriormente. + +Configurar Chave SSH no Portal SPB +---------------------------------- + +Primeiramente, para conseguir configurar sua chave SSH no seu perfil do SPB é necessário estar registrado no portal. O registro pode ser feito em: https://portal.softwarepublico.gov.br/account/register . + +Após efetuar o login no Portal SPB, clique em ``Código``, no menu principal do portal, e em seguida em ``Perfil``. Dentro do seu perfil, existe um outro menu e uma das suas opções é ``Chaves SSH``, clique nela. Nesta página você pode gerenciar suas chaves SSH, então clique em **Adicionar Chave SSH**. Utilize o comando abaixo no terminal para obter sua chave SSH:: + + $ cat ~/.ssh/id_rsa.pub + ssh-rsa AAARB3NzaC1yc2EAAAADAQEVAAABAQCops6nAMYWRR/ + w9fDZe6LIVh5y9YwW9c10F0DCUkvEYp8E3gtmKOIz5vQewqAtqUnHmFWcIzEPhqU/Pi2UCnPfFUz+MbBZSEmSbe9mJa/ + aVpR5uBfEscVPH+mN0bdsqDUHhSTboSe64D+MCbflKhVyjwL/wZuXdzmFtJ4Jv8D7aLm5bNQRfw0oCE7cWYc3O9PULSS9005nO91Tk4 + w5gaA9B4i3GNRnbhaUgjis6pD9ln9dY2LmCs1mLRkZg09ocMdzq3eohhfpPTykPE+I6WDAyYFPyIJDT+AQQQ1qvFnmgYg6HpgWpXBv2 + w8fWcPu5nc8pmKRwmzO2LSKvdfWIXgd nome-do-usuario@hostname + +Copie o output do comando ``cat ~/.ssh/id_rsa.pub``, digite um título para a chave no campo ``Titulo``, cole a chave no campo ``Chave`` e clique em **Adicionar Chave**. + +Pronto! Sua chave foi adicionada e vinculada à sua conta no Portal SPB. + +Copiar Chave SSH +---------------- +Para evitar o trabalho de ter que digitar a senha dos servidores toda vez que uma conexão SSH for feita, podemos apenas copiar a chave SSH para o servidor e, assim, o servidor já reconhece a sua chave e não solicita a senha. + +Os comandos que podem ser utilizados para realizar a cópia da chave são:: + + $ ssh-copy-id usuario@ip-hostname + $ ssh-copy-id ip-hostname + +Onde: + +* ``usuario``: é o usuário que você deseja usar para entrar na máquina destino. Caso esse parametro não seja passado, o próprio comando, automaticamente, utiliza o usuário logado na máquina no momento em que foi executado como parâmetro. +* ``ip-hostname``: é o ip ou hostname da máquina destino. + +Ao executar o comando, será solicitada a senha do usuário fornecido. Uma vez informada, as próximas conexões via SSH, utilizando esse usuário, não precisarão ser autenticadas. + +No contexto do SPB, é necessário que a chave da estação de trabalho seja copiada para **todas** as máquinas do ambiente @@SPB_ENV@@, ou seja, o comando acima deverá ser executado para cada ip listado em ``config/@@SPB_ENV@@/ips.yaml``:: + + @@config(ips.yaml)@@ + +Caso os ambientes já tenham sido convergidos anteriormente, não será possível executar o comando ``ssh-copy-id``, pois as portas SSH estarão fechadas pelo firewall. Nesse caso, a chave deverá ser copiada manualmente:: + + $ cat ~/.ssh/id_rsa.pub + ssh-rsa AAARB3NzaC1yc2EAAAADAQEVAAABAQCops6nAMYWRR/ + w9fDZe6LIVh5y9YwW9c10F0DCUkvEYp8E3gtmKOIz5vQewqAtqUnHmFWcIzEPhqU/Pi2UCnPfFUz+MbBZSEmSbe9mJa/ + aVpR5uBfEscVPH+mN0bdsqDUHhSTboSe64D+MCbflKhVyjwL/wZuXdzmFtJ4Jv8D7aLm5bNQRfw0oCE7cWYc3O9PULSS9005nO91Tk4 + w5gaA9B4i3GNRnbhaUgjis6pD9ln9dY2LmCs1mLRkZg09ocMdzq3eohhfpPTykPE+I6WDAyYFPyIJDT+AQQQ1qvFnmgYg6HpgWpXBv2 + w8fWcPu5nc8pmKRwmzO2LSKvdfWIXgd nome-do-usuario@hostname + +O output do comando acima é a sua chave pública, ela deverá ser copiada e colada, manualmente, em ``~/.ssh/authorized_keys`` do usuário desejado. Esse procedimento deve ser repetido em todas as máquinas listadas em ``config/@@SPB_ENV@@/ips.yaml``. \ No newline at end of file diff --git a/docs/arquitetura.rst.in b/docs/arquitetura.rst.in index 4b67a9d..342ce79 100644 --- a/docs/arquitetura.rst.in +++ b/docs/arquitetura.rst.in @@ -50,7 +50,7 @@ originada da integration. Conexões na porta 22 da máquina reverseproxy são redirecionadas para integration. As máquinas email, social e database aceitam conexão SSH vindas da integration na porta 22 e a reverseproxy em uma porta alternativa, especificada no arquivo de configuração do ambiente, -config/$SPB_ENV/config.yaml pelo valor passado a 'alt_ssh_port'. +config/$SPB_ENV/config.yaml pelo valor passado a 'alt_ssh_port'. Por exemplo, para se conectar na máquina email é necessário estabelecer conexão SSH na porta 22 da reverseproxy, esta conexão será redirecionada para a máquina @@ -77,7 +77,7 @@ ser obtido a partir do comando:: $ git clone git@portal.softwarepublico.gov.br:softwarepublico/softwarepublico.git Note que para tal, é necessário possuir uma conta no Portal do SPB com chaves -SSH configuradas. +SSH configuradas. Para mais informações sobre essas configurações, veja a :doc:`/apoio`. Este repositório contém scripts que realizam todos os passos necessários para a instalação, configuração e manutenção do ambiente. Isto é feito diff --git a/docs/implantacao.rst.in b/docs/implantacao.rst.in index 946bef1..2a5395e 100644 --- a/docs/implantacao.rst.in +++ b/docs/implantacao.rst.in @@ -36,7 +36,7 @@ Obtendo o repositório de configuração ------------------------------------- Para iniciar, é necessário uma conta e usuário no SPB, com uma chave SSH -configurada. +configurada. Mais informações em :doc:`/apoio`. Para obter o repositório de configuração, é necessário clonar o repositório com ``git``:: @@ -49,7 +49,6 @@ onde foi clonado o repositório:: $ cd softwarepublico/ - Preparação dos servidores ------------------------- @@ -64,6 +63,7 @@ Preparação dos servidores * ter acesso SSH configurado via chave SSH para evitar digitar senha, a partir da estação de trabalho utilizada. Ou seja, a chave pública SSH **da estação de trabalho** deve ser copiada para cada servidor. + Para mais informações, veja a :doc:`/apoio`. * O ``sudo`` não deve estar configurado com a opção ``requiretty``. Se houver uma linha como a seguinte em ``/etc/sudoers``, ela deve ser @@ -129,6 +129,8 @@ DNS: .. include:: dns.rst +.. _verificandoambiente: + Verificando o ambiente ---------------------- @@ -159,7 +161,7 @@ ser omitido se você tiver configurado o *default* em ``local.rake``. Para testar a conectividade às máquinas, devemos antes realizar a preconfiguração das máquinas, caso o sistema nunca tenha sido instalado. -Note que se este passo só deve ser realizado uma única vez:: +Note que se este passo deve ser realizado uma **única vez**:: $ rake preconfig SPB_ENV=@@SPB_ENV@@ @@ -186,9 +188,10 @@ parecido com o seguinte:: reverseproxy: Qui Mai 14 18:59:28 BRT 2015 Se o resultado se parece com o exemplo acima, e você não precisou digitar a sua -senha nehuma vez, significa que 1) você conseguiu conectar em todas as máquinas -e 2) o sudo sem senha está configurado corretamente. Está tudo certo para -começar! +senha nehuma vez, significa que: + +1) você conseguiu conectar em todas as máquinas. +2) o sudo sem senha está configurado corretamente. Está tudo certo para começar! Nota sobre certificado SSL -------------------------- @@ -227,7 +230,7 @@ Primeira instalação Uma vez configurados os parâmetros em ``config/@@SPB_ENV@@/``, podemos dar início à instalação. O primeiro passo é uma preconfiguração que -precisamos fazer, caso não tenha sido feito em "Verificando o Ambiente":: +precisamos fazer, caso não tenha sido feito em :ref:`verificandoambiente`:: $ rake preconfig SPB_ENV=@@SPB_ENV@@ diff --git a/docs/index.rst.in b/docs/index.rst.in index 4cc2dfb..d088c3d 100644 --- a/docs/index.rst.in +++ b/docs/index.rst.in @@ -10,3 +10,4 @@ Software Público Brasileiro: Manual de Operação (@@SPB_ENV@@) manutencao backup firewall + apoio -- libgit2 0.21.2