Software Público Brasileiro

Documentação de Apoio
=====================
.. _referencia:

Configuração de Usuário
---------------

Para a criação de usuário utilize (o comando deve ser executado por um
usuário com permissão sudo)::

    # adduser <NOME DO USUÁRIO>

Edite o arquivo de sudoers com o comando::

    # visudo

Adicione a linha no arquivo::

    <NOME DO USUÁRIO> ALL=(ALL:ALL) NOPASSWD:ALL


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``.

Git push com HTTPS
-----------------

Para a utilização do git com protocolo HTTPS, existem dois casos básicos: aqueles que já tinham cadastro e os novos usuários. Se for o primeiro cadastro, pule o passo "0" descrito abaixo.

0) Mudar senha no colab (para usuários já cadastrados): No topo da tela, do lado direito, você verá um icone circular no qual você deve clicar. Na nova tela apresentada, escolha a opção "Meu perfil" e em seguida escolha a opção "Editar Perfil". Na nova tela, clique na opção "Trocar senha". Digite a sua senha original, e a nova senha.
1) Para clonar o repositório via http, use o comando abaixo:

  $ git -c http.sslVerify=false clone <seu-repositório>

2) Para realizar o push via http, faça:

  $ cd <caminho-do-diretório-do-projeto>
  $ git config http.sslVerify "false"
  $ git push <remote> <branch>

3) Informe o seu login e senha.

No Portal do Software Público Brasileiro, assim como em outros portais do governo, temos problemas com o certificado digital. Para o git conseguir realizar as operações usando HTTPS é necessário ignorar o certificado, por isto as opções com "sslVerify".

Integração manual entre repositórios
---------------------------------

Para empurrar modificações para mais de um repositório, por exemplo os repositórios do Portal do Software Público Brasileiro e Github, é necessário fazer algumas modificações nas configurações no git localmente (lado do cliente). Para isso, vamos configurar um apelido (alias) que aponte para as URLs dos nossos repositórios, e quando o comando ``git push <alias> <branch>`` for executado, as modificações serão empurradas para todos os nossos repositórios previamente configurados. Ou seja, apenas um comando será executado e todos os repositórios serão atualizados.

Para realizar essa configuração é necessário que tenha o git instalado com um bash(terminal) e o repositório do seu projeto clonado localmente. Tendo isso, abra o bash e execute os comandos a seguir::

  $ cd <caminho-do-diretório-do-projeto>
  $ git remote set-url --add --push <apelido> <URL-repo1>
  $ git remote set-url --add --push <apelido> <URL-repo2>
  $ git remote set-url --add --push <apelido> <URL-repo3>

Lembrando que o <apelido> de todos deve ser o mesmo, usualmente é usado o apelido "origin". Com isso, ao empurrar as suas modificações todos os repositórios configurados serão atualizados.


Gerenciando listas de email
---------------------------
O Mailman fornece alguns scripts para administração das listas de email, tais programas podem ser encontrados na máquina ``integration`` em ``/usr/lib/mailman/bin``.

Removendo uma lista::

  $ cd /usr/lib/mailman/bin
  $ sudo ./rmlist nome_da_lista

Note que o comando acima não remove os históricos (archives) da lista. Para remover uma lista juntamente com seu histórico::

  $ cd /usr/lib/mailman/bin
  $ sudo ./rmlist -a nome_da_lista

Além disto, o Colab também armazena os dados relacionados aos históricos das listas. Para remover tais dados  deve-se acessar ``<DOMINIO>/colab/admin/``, onde ``<DOMINIO>`` é o domínio do ambiente em que se deseja realizar a operação, como por exemplo: portal.softwarepublico.gov.br, clicar em Mailing Lists e remover a lista que desejar. Note que os dados não poderão ser restaurados.

Alterando a senha de administrador do Mailman::

  $ cd /usr/lib/mailman/bin
  $ sudo ./mmsitepass nova_senha

Gerenciando aliases de email
----------------------------

Como a máquina ``integration`` é o destino final de emails recebidos pela
plataforma, é nela onde deve ser feita a gestão de aliases
``@@@external_hostname@@``.

Configuração inicial
********************

**Nota::** esta configuração inicial só precisa ser feita uma vez. Após a primeira vez, apenas os passos em "Adicionando/modificando aliases" são necessários.

Instruir o postfix a ler os aliases de um arquivo, digamos,
``/etc/postfix/aliases``::

  $ sudo postconf virtual_alias_maps=hash:/etc/postfix/aliases

Em seguida é necessário fazer com que o serviço ``postfix`` recarregue as suas
configurações::

  $ sudo systemctl reload postfix

Adicionando/modificando aliases
*******************************

Os aliases devem então ser mantidos neste arquivo. Um alias por linha, no
formato ``<ALIAS> <DESTINO>``. Exemplo::

  admin@@@external_hostname@@         softwarepublico@planejamento.gov.br
  exemplo@@@external_hostname@@       exemplo@planejamento.gov.br

Após cada alteração no ``/etc/postfix/aliases`` (incluindo a sua criação), é
necessário compilá-lo num banco de dados otimizado com o seguinte comando::

  $ sudo postmap /etc/postfix/aliases