Feat: migrate docs from Ikiwiki to MkDocs

25 files changed, 1665 insertions, 0 deletions

diff --git a/docs/audit.md b/docs/audit.md
new file mode 100644
index 0000000..74a932b
--- /dev/null
+++ b/docs/audit.md
@@ -0,0 +1,16 @@
+# Auditoria 
+
+## Resetando senhas em banco de dados
+
+Considerando que as senhas se encontram na coluna `pass` da tabela `users` e
+que se encontram armazenadas em hashes md5, utilize o comando
+
+    update users set pass = md5('SENHA');
+
+onde `SENHA` é uma senha longa e complicada.
+
+## Busca por vírus
+
+    freshclam --datadir=$datadir
+    clamscan --database=$datadir -r *
+
diff --git a/docs/backup.md b/docs/backup.md
new file mode 100644
index 0000000..657262c
--- /dev/null
+++ b/docs/backup.md
@@ -0,0 +1,7 @@
+# Backup
+
+* [Conceitos](concepts).
+* [Convenções](conventions).
+* [Métodos](methods).
+* [Restauração](restore).
+* [Migração de sites](migration).
diff --git a/docs/backup/concepts.md b/docs/backup/concepts.md
new file mode 100644
index 0000000..828ffce
--- /dev/null
+++ b/docs/backup/concepts.md
@@ -0,0 +1,78 @@
+# Da natureza dos backups 
+
+Um backup pode ser entendido como qualquer cópia feita para assegurar a
+existência de uma informação ou configuração em virtude da falta de garantia de
+que seu "suporte" físico consiga mantê-la.
+
+Podemos fazer uma analogia bem limitada com uma floresta com espécies
+endêmicas: se ocorrer uma queimada, as espécies se perdem a não ser que exista
+um banco de sementes intacto que permita o plantio das espécies ameaçadas.
+
+Esse exemplo da floresta é limitado porque no caso de um backup de dados
+digitais a informação se preserva ao transportá-la para outro suporte físico
+(isto é, configurar o conjunto de estados possíveis do "suporte" físico, por
+exemplo disco rígido, DVD, pendrive, de modo a reproduzir uma dada configuração
+presente anteriormente num outro suporte físico: o backup é a reprodução de um
+conjunto de estados de um sistema), o que não ocorre num reflorestamento.
+
+Guardar TODA informação existente em uma floresta, numa vizinhança ou mesmo na
+memória de um povo é uma tarefa inatingível, o que faz qualquer floresta,
+qualquer vizinhança ou povo insubstituíveis. Vejamos a cultura: ela se reproduz
+e contamina, quase sempre com mutações...
+
+Nesse sentido, backups de dados digitais são tarefas bem mais simples e
+possíveis, porque os temos e os conseguimos copiá-los com exatidão. Não há uma
+receita única para fazer um backup digital: a simples cópia de um arquivo de um
+suporte a outro já pode ser considerado como um backup.  Parâmetros dos backups 
+
+Existem diversos parâmetros importantes quando se trata de um backup digital:
+
+1. Periodicidade.
+2. Incrementos.
+3. Largura de banda.
+4. Segurança e integridade dos dados. 
+
+O primeiro deles é a própria modifição realizada pelo uso dos dados. Um sítio
+em HTML, Wiki ou Drupal nem sempre -- imagino que no caso dos sítios aqui da
+vizinhana quase nunca -- se mantém estáticos, sem modificações. Por isso, um
+backup de um sítio há um mês não conterá as alterações de um sítio realizadas
+nas duas últimas semanas. O primeiro parâmetro então a periodicidade na qual os
+backups são realizados.
+
+O segundo parâmetro mais ou menos conseqüência do primeiro: se copiarmos um
+sítio de um disco para outro a cada semana, podemos atualizar o backup com as
+alterações realizadas num sítio mas ao mesmo tempo, caso não tenhamos cuidado,
+podemos também estar apagando o estado que o sítio tinha anteriormente, antes
+dessas últimas modificações. Em outras palavras, o segundo parâmetro de um
+backup, a quantidade de "incrementos" que teremos: podemos copiar um sítio para
+um DVD e, daqui a duas semanas, copiar novamente mas para um outro DVD. Se por
+um acaso precisarmos de uma informação que continha há duas semanas no sítio,
+basta que a resgatemos do primeiro DVD. Agora, manter esses "incrementos", isto
+é, um DVD para cada backup, tem um custo físico e nesse caso ecológico muito
+grande. É preciso então escolher um número de "incrementos" que permita que
+tenhamos uma boa amostragem das modificações realizadas num sítio sem que
+gastemos muito tempo, espaço em disco ou mídia física com tal atividade.
+
+Não entraremos em detalhes, mas um backup que queira dar conta de modificações
+realizadas em intervalos de duas semanas deve ser realizado pelo menos a cada
+semana (teorema da amostragem de
+[Nyquist-Shannon](http://en.wikipedia.org/wiki/Nyquist-Shannon)).
+
+O terceiro parâmetro é a largura de banda. Copiar um sítio de um lugar para
+outro demanda um tempo de transferência. No caso de sítios muito grandes, a
+cópia pode demorar tempo demais e o backup se torna mais uma dificuldade do que
+um benefício. Por isso, a largura de banda pode obrigar que façamos alguns
+truques: a compressão dos dados (arquivo .zip, tar.gz, tar.bz2, etc) e a cóipia
+apenas dos arquivos que foram modificados. Por exemplo, num sítio que tem
+vários vídeos nem todos eles precisam ser copiados a cada backup, mas sim os
+novos ou aqueles que foram modificados.
+
+O quarto parâmetro é a segurança e a integridade dos dados: se você possui
+informações sensíveis (senhas, contatos e tudo o mais que for delicado para se
+tornar público ou cair em mãos erradas), tome cuidado para onde vai copiar
+essas informações e onde as deixar armazenadas. Da mesma forma, a checagem da
+integridade dos arquivos verifica se estes não sofreram alterações durante o
+procedimento de backup.
+
+Em resumo, esses são os quatro parâmetros básicos para um backup:
+periodicidade, incremento, largura de banda e segurança/integridade. 
diff --git a/docs/backup/conventions.md b/docs/backup/conventions.md
new file mode 100644
index 0000000..cb5c698
--- /dev/null
+++ b/docs/backup/conventions.md
@@ -0,0 +1,50 @@
+# Convenções
+
+Esta página contém esboço para as convenções de intercâmbio de backups entre
+servidores. Qualquer que seja o método de backup, ele deve satisfazer as
+seguintes condições:
+
+1. Deve ser incremental para que vários estados diários sejam possíveis de se
+   obter.
+2. Devem ser gerenciados pelo backupninja.
+3. Cada projeto cuida dos seus próprios backups, mesmo que estes estejam sendo
+   enviados para o servidor de outro projeto.
+
+## Armazenamento
+
+1. Backups hospedados em `/var/backups`, mesmo que seja symlink para outro
+   local.
+2. Arquivos de log de backup em `/var/log/{backup,backupninja.log}`, rodando
+   via logrotate.
+3. Backups remotos de servidores e sites em subpastas do tipo
+   `/var/backups/remote/nome-da-camada.projeto.org/handler`.
+4. Backups locais criptografados em `/var/backups/duplicity` e sem backup da
+   pasta `/var/backups/remote`.
+5. Máquinas enviando backups para outros locais enviam apenas o backup local
+   criptografado.
+
+## O que incluir nos backups locais
+
+Talvez a convenção mais forte para a inclusão de arquivos seja aquela na qual a
+inclusão de novos arquivos e pastas nos backups seja automática. Assim, a
+convenção adotada é a realização de backups das pastas
+
+* `/etc`
+* `/var`
+* `/home`
+
+Para que a convenção funcione, é indispensável que conteúdos (dados) hospedados
+sejam armazenados apenas nestas pastas. Como a `/etc` é uma pasta reservada ao
+armazenamento de configurações, restam apenas `/var` e `/home` para o
+armazenamento de dados. Assim, a utilização de pastas do tipo `/var/svn`,
+`/var/www`, etc garantem a inclusão automática de todo o conteúdo hospedado nos
+backups.
+
+## Não incluir em backups locais
+
+As seguintes pastas não devem ser incluídas em backups:
+
+* `/var/backups/duplicity`
+* `/var/backups/remote`
+* `/var/vservers`
+* `/vservers`
diff --git a/docs/backup/methods.md b/docs/backup/methods.md
new file mode 100644
index 0000000..456e372
--- /dev/null
+++ b/docs/backup/methods.md
@@ -0,0 +1,95 @@
+# Métodos para backup remoto
+
+Esta página contém um estudo dos métodos de produção, transferência e
+armazenamento de backups, divididos nas partes:
+
+* Métodos de tranferência
+* Métodos de armazenamento 
+
+A discussão aqui não tem caráter prático mas meramente teórico, sem menção às
+implementações dos métodos. Para isso, veja a página
+[Convencoes](../conventions).
+
+## Métodos de transferência
+
+### Método 1: rsync + hardlinks 
+
+Vantagens:
+
+* Economiza espaço
+* Simples de configurar 
+
+Desvantagens:
+
+* Precisa rodar como root nas duas máquinas/vservers para preservar permissões
+* Workarround: criar um `FILELIST.TXT` para cada vserver indicando as
+  permissões e os proprietários dos arquivos, juntamente com um script que
+  corrija todas essas permissões no caso de um restauro de backup.
+
+### Método 2: tar + ssh
+
+Esse método consiste em criar um `.tar.bz2` num pipe direto para o servidor
+remoto, sem escrita local em disco, isto é,
+
+    nice -n 19 tar c /mnt/backup/servidor/vservers/vservers.0/ | bzip2 | \
+      ssh servidor-remoto "cat - > servidor-vservers-0.tar.bz2"
+
+Vantagens:
+
+* o arquivo transferido preserva todas as permissões do seu conteúdo
+* no servidor remoto o arquivo fica compactado
+* rodar com um nice alto garante que esse comando não atrapalhará o
+  funcionamento normal do sistema.
+
+Para economizar espaço na máquina remota, podemos operar com backups
+incrementais:
+
+    nice -n 19 tar cv /mnt/backup/servidor/vservers/vservers.0/ \
+      --listed-incremental=/var/log/backup/vservers.snar \ | bzip2 | ssh \
+      servidor-remoto "cat - > servidor-vservers-`date +%w`.tar.bz2" >> \
+      /var/log/backup/servidor-remoto.log
+
+Nesse caso, uma vez por semana as seguintes operações devem ser feitas:
+
+* Mover todos os arquivos para uma pasta da "semana passada".
+* Iniciar um novo full-dump.
+
+Desvantagem: full-dump semanal.
+
+### Método 3: GNU backup
+
+O script backup que acompanha o GNU tar pode ser usado para fazer dumps
+incrementais locais que depois são enviados aos servidores remotos.
+
+Desvantagem: arquivos não podem ser modificados durante a confecção do backup.
+
+### Método 4: duplicity
+
+* <http://www.nongnu.org/duplicity>
+* backups criptografados
+
+### Método 5: rdiff-backup
+
+* <http://www.nongnu.org/rdiff-backup>
+
+## Métodos de armazenamento
+
+### Método 1: vserver dedicado a backups
+
+Cada servidor possui um único vserver dedicado a puxar os backups dos outros
+servidores. Esse vserver não terá acesso externo e por isso é a abordagem mais
+segura de armazenamento.
+
+Veja uma discussão sobre isso em
+<https://docs.indymedia.org/view/Sysadmin/PullBackupsForParanoiacs>.
+
+### Método 2: vservers dedicados a cada servidor
+
+Cada servidor possui seu próprio vserver em cada máquina remota onde ele fizer
+backup. Nesse vserver os backups remotos poderão ser feitos como root sem
+acarretar perda de segurança para a máquina remota, o que faz essa ser a
+abordagem mais flexível para puxar ou receber backups remotos.  Backups
+criptografados.
+
+Veja uma discussão sobre isso em
+<https://wiki.boum.org/TechStdOut/EncryptedBackupsForParanoiacs>.
diff --git a/docs/backup/migration.md b/docs/backup/migration.md
new file mode 100644
index 0000000..49026eb
--- /dev/null
+++ b/docs/backup/migration.md
@@ -0,0 +1,80 @@
+# Migração de Sites
+
+## Sites
+
+Parâmetros iniciais:
+
+    ORIGIN="hostname-origem"
+    DEST="fqdn-destino:porta-ssh"
+
+Montando manualmente a lista de sites:
+
+    IKIWIKIS="lista de ikiwikis"
+    SITES="$IKIWIKIS outros sites"
+
+Montando a partir das definições do puppet:
+
+    hydra sarava list-sites $ORIGIN
+
+## DNS
+
+Proceda com a mudança de DNS para os sites, atualizando o repositório dns.git.
+
+## Backup
+
+Na origem:
+
+    hydractl backup-sites $SITES
+
+## Cópia
+
+Na origem:
+
+    hydractl backup-copy-sites $DEST $SITES
+
+A senha do usuário `backups` está no keyringer.
+
+Para agilizar, copie **temporariamente** a chave pública de de `root@$ORIGIN`
+para `backups@DEST:~/.ssh/authorized_keys`.  Isso evitará a digitação excessiva
+da senha do usuário `backups`.
+
+## Git
+
+Caso os repositórios `git` também estejam sendo migrados, crie uma senha
+temporária para o `gitolite` na máquina de destino e proceda com a cópia do
+material:
+
+    su gitolite -c "rsync -avz --delete -e 'ssh -p porta-ssh' /var/git/ fqdn-destino:/var/git/"
+
+Você também precisará alterar a chave de acesso de `root@ORIGIN` para
+`root@DEST` na configuração do gitolite.
+
+## Habilitando
+
+Habilite os sites pelo puppet, mudando o nome do servidor no campo `tag` de
+cada definição.
+
+Verifique se existem usuários e grupos em `users::virtual` associados a esses
+sites, fazendo a alteração conforme necessário.
+
+Aplique o catálogo no servidor de destino. Eventualmente, desabilite o puppet
+no servidor de origem com o comando
+
+    hydractl puppet-disable
+
+Isso evitará que os sites sejam apagados antes que tenhamos certeza que foram migrados com
+sucesso.
+
+## Restore
+
+No destino:
+
+    hydractl backup-restore-sites $ORIGIN $SITES
+
+No caso de um único site:
+
+    hydractl backup-restore-sites backups $ORIGIN nome-do-sitio
+
+Reprepro:
+
+    hydractl backup-restore-reprepro $ORIGIN
diff --git a/docs/backup/restore.md b/docs/backup/restore.md
new file mode 100644
index 0000000..3b5a2b8
--- /dev/null
+++ b/docs/backup/restore.md
@@ -0,0 +1,99 @@
+# Restauração de backups
+
+O procedimento de restore pode ser feito de várias maneiras:
+
+1. A partir dos backups remotos de um nodo.
+2. A partir do backup local de um nodo.
+3. A partir do backup gerado de um site em funcionamento.
+
+O ciclo completo pode ser dividido em três partes:
+
+1. Geração do backup.
+2. Transferência do backup.
+3. Restauração do backup.
+
+A geração e transferência de backups já estão bem sólidas por conta do
+[puppet-backup](https://git.$dominio/?p=puppet-backup.git;a=summary
+puppet-backup). Tratemos da parte manual dos procedimentos usando a [Hydra
+Suite](http://git.$dominio/?p=hydra.git;a=summary).
+
+## Restauro a quente
+
+O restauro a quente ocorre quando:
+
+* O serviço de origem se encontra online OU.
+* Queremos restaurar uma versão anterior do serviço no mesmo servidor em que
+  ele se encontra OU.
+* Quando temos condições de realizar um backup logo antes do serviço sair do ar
+  e migrá-lo para um nodo de destino.
+
+Para fazer o backup do site em `/var/site/backups/site/$sitio`:
+
+    hydractl backup-site $sitio
+
+Para fazer o backup de vários sites:
+
+    hydractl backup-sites $sitio $sitio1 $sitio2
+    hydractl backup-sites # faz backup de todos os sites
+
+O `backup-sites` faz inclusive o backup do `svn.$dominio` e do `git.$dominio`,
+o que nestes casos significa a cópia dos repositórios:
+
+    hydract backup-site svn
+    hydract backup-site git
+
+Para copiar o backup para `$servidor:/var/site/backups/site/$sitio`:
+
+    hydractl backup-copy-site  $servidor $sitio
+    hydractl backup-copy-sites $servidor $sitio $sitio1 $sitio2
+    hydractl backup-copy-sites $servidor # copia todos os sitios
+
+Para restaurar o backup copiado a partir do `$servidor`:
+
+    hydractl backup-restore-site backups $servidor $sitio
+
+Tal restauro de backups necessita que o site já esteja definido no nodo através das configurações do puppet.
+
+## Restauro a frio
+
+O restauro a frio ocorre quando o serviço está offline, em geral quando há
+algum problema no nodo onde ele estava rodando.
+
+Primeiramente, pode ser que queiramos copiar o backup armazenado num servidor
+remoto para o local onde fazermos o restauro do serviço. O ideal é que isso já
+seja feito automaticamente pelo sistema de backups, mas no caso de servidores
+novos isso ainda não teve a oportunidade de acontecer.
+
+Para isso, usamos o seguinte comando no nodo onde o backup se encontra:
+
+    hydractl backup-copy ORIG DEST # transfere /var/backups/remote/ORIG.$domain para DEST
+
+No nodo de destino, primeiro restauraremos backups cifrados de
+`/var/backups/remote/ORIG.$domain/{rsync,rdiff}` para
+`/var/backups/remote/ORIG.$domain/restore`:
+
+    hydractl backup-restore ORIG
+
+Em seguida, procedemos com o restauro de aplicações.
+
+### Restauro a frio do nodo de email
+
+    hydractl backup-restore-mail      ORIG
+    hydractl backup-restore-database  ORIG postfix
+    hydractl backup-restore-sympa     ORIG
+    hydractl backup-restore-schleuder ORIG
+    hydractl backup-restore-firma     ORIG
+
+    for service in apache2 sympa dovecot postfix postgrey; do
+      /etc/init.d/$service restart
+    done
+
+    hydractl backup-restore-site ORIG postfixadmin
+    chown root.www-data /var/sites/postfixadmin/site/config.inc.php
+
+    hydractl backup-restore-database ORIG roundcube
+    dpkg-reconfigure roundcube-core
+
+### Restauro a frio de um nodo web
+
+    hydractl backup-restore-svn ORIG
diff --git a/docs/bootless.md b/docs/bootless.md
new file mode 100644
index 0000000..2cca9b3
--- /dev/null
+++ b/docs/bootless.md
@@ -0,0 +1,3 @@
+# Bootless
+
+Vide [Projeto Bootless](https://bootless.sarava.org).
diff --git a/docs/bootstrap.md b/docs/bootstrap.md
new file mode 100644
index 0000000..653f517
--- /dev/null
+++ b/docs/bootstrap.md
@@ -0,0 +1,288 @@
+# Bootstrap de uma configuração completa
+
+Este documento tem como objetivo descrever o **processo de bootstrap** de uma
+configuração completa de um servidor utilizando o [Padrão Saravá](/). O
+*processo de bootstrap* pode ser compreendido como "o processo de coordenar
+diversos processos interdepententes de forma que seja atingida uma configuração
+sistêmica estável".
+
+Para este processo, utilizaremos as seguintes ferramentas:
+
+* [Debian GNU/Linux 6.0](http://www.debian.org/releases/squeeze/).
+* [Linux-VServer](http://linux-vserver.org/) ([pacote do debian](http://packages.debian.org/squeeze/linux-image-2.6-vserver-686)).
+* [Git](http://git-scm.com/) e [gitosis](http://swik.net/gitosis).
+* [puppet-bootstrap](http://git.sarava.org/?p=puppet-bootstrap.git;a=summary).
+* [hydra](http://git.sarava.org/?p=hydra.git;a=summary).
+
+Os seguintes estágios fazem parte de uma instalação padrão completa:
+
+## Instalação do sistema padrão na máquina hospedeira
+
+Documentação [aqui](install.md).
+
+## Configuração da máquina hospedeira
+
+Configure algumas variáveis de ambiente:
+
+    export domain="projeto.org"
+    export hostname=`hostname | sed -e s/\\\\..*$//`
+    export puppet_bootstrap_dir=/var/tmp/puppet-bootstrap
+    export PUPPETLIB=${puppet_bootstrap_dir}/modules
+
+Configure o arquivo `/etc/hosts` (a ordem dos hostnames influencia nos resultados do `facter`):
+
+    cat > /etc/hosts <<EOF
+    127.0.0.1 ${hostname}.${domain} ${hostname}
+    127.0.0.1 localhost
+    EOF
+
+Instale o git e o puppet e clone o repositório `puppet-bootstrap`:
+
+    apt-get -y install git-core puppet wipe
+    git clone git://git.sarava.org/puppet-bootstrap ${puppet_bootstrap_dir}
+
+Altere o arquivo `${puppet_bootstrap_dir}/manifests/config.pp` de acordo com suas necessidades.
+
+Prepare o servidor para a utilização do puppet.
+
+    puppet apply -d -v ${puppet_bootstrap_dir}/manifests/stage0.pp
+
+Crie um vserver para abrigar o nó administrativo:
+
+    puppet apply -d -v ${puppet_bootstrap_dir}/manifests/host-stage1.pp
+
+Anote a fingerprint da chave ssh do vserver:
+
+    vserver ${hostname}-master exec ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key.pub
+
+## Configuração do nó administrativo
+
+A partir deste momento, vamos trabalhar apenas no nó administrativo recém criado.
+
+Copie o `puppet-bootstrap` e a configuração padrão para o vserver e limpe os rastros:
+
+    echo LANG=C > /var/vservers/${hostname}-master/etc/default/locale
+    cp -r ${puppet_bootstrap_dir} \
+      /var/vservers/${hostname}-master/${puppet_bootstrap_dir}
+    cp -r /usr/local/puppet \
+      /var/vservers/${hostname}-master/usr/local/puppet
+    wipe -rcfq -S r -R /dev/urandom ${puppet_bootstrap_dir} /usr/local/puppet
+
+Acesse o vserver e instale algumas ferramentas:
+
+    vserver ${hostname}-master enter
+    apt-get update
+    apt-get -y upgrade
+    apt-get -y install git puppet puppetmaster wipe
+
+Configure o hostname e domínio do nó administrativo:
+
+    cat > /etc/hosts <<EOF
+    127.0.0.1 ${hostname}-master.${domain} ${hostname}
+    127.0.0.1 localhost
+    EOF
+
+Prepare o vserver para a utilização do puppet.
+
+    puppet apply -d -v ${puppet_bootstrap_dir}/manifests/stage0.pp
+    puppet apply -d -v ${puppet_bootstrap_dir}/manifests/admin-stage1.pp
+
+## Criação de repositórios padrão
+
+Dê acesso ao repositório administrativo do gitosis a um usuário:
+
+    sudo -H -u gitosis gitosis-init < FILENAME.pub
+
+Clone o repositório administrativo do gitosis remotamente:
+
+    git clone ssh://gitosis@servidor.${domain}:2202/gitosis-admin
+
+Altere o arquivo `gitosis-admin/gitosis.conf` do repositório clonado e crie um
+repositório para a configuração do puppet e um repositório para suas chaves
+criptográficas:
+
+    [gitosis]
+    daemon      = no
+    gitweb      = no
+    public_http = no
+
+    [group admin]
+    writable = gitosis-admin puppet keyring
+    members = usuario@maquina
+
+Empurre as mudanças para o servidor:
+
+    git commit -a -m "Adicionando repositórios para puppet e keyring"
+    git push origin master
+
+Para adicionar um novo usuário ao gitosis, basta adicionar as chaves públicas
+ssh ao diretório `gitosis-admin/keydir/` com um nome de arquivo do tipo
+`usuario@maquina.pub`.
+
+## Configuração do repositório puppet
+
+Altere as configurações padrão do puppet em `/usr/local/puppet/default-conf` de
+acordo com suas necessidades e incialize os repositórios em `/etc/puppet` e
+`/var/git/repositories/puppet`):
+
+    /etc/init.d/puppetmaster stop
+    rm -rf /etc/puppet && mkdir /etc/puppet
+    cd /etc/puppet
+    cp -r /usr/local/puppet/default-conf/* .
+    wipe -rcfq -S r -R /usr/local/puppet
+    git init
+    git add *
+    puppet-bootstrap add-submodules /etc/puppet
+    git commit -m "Initial config."
+    git clone --bare /etc/puppet/ /var/git/repositories/puppet.git
+    chown -R gitosis:gitosis /var/git/repositories/puppet.git
+
+Agora já podemos clonar o repositório de configurações do puppet remotamente:
+
+    git clone ssh://gitosis@${hotname}.${domain}:2202/puppet.git
+
+## Configuração da hydra
+
+Esta parte da instalação gera chaves criptográficas e portanto deve ocorrer em
+uma máquina com um nível de segurança significativo (criptografia de disco,
+bootless, etc).
+
+Instale `hydra` e `keyringer`:
+
+    sudo apt-get -y install git-core
+    # hydra
+    sudo git clone git://git.sarava.org/hydra /usr/local/hydra
+    sudo ln -sf /usr/local/hydra/hydra /usr/local/sbin/hydra
+    sudo ln -sf /usr/local/hydra/hydra /usr/local/sbin/hydractl
+    # keyringer
+    sudo git clone git://git.sarava.org/keyringer /usr/local/keyringer
+    sudo ln -sf /usr/local/keyringer/keyringer /usr/local/bin/keyringer
+
+Tenha certeza que possui em seu chaveiro gpg as chaves dos usuários que irão
+acessar o repositório de chaves. Crie um keyring para o projeto clonando o
+repositório configurado:
+
+    keyringer projeto init ~/projeto/keyring
+    cd ~/projeto/keyring
+    git init
+    git remote add origin ssh://gitosis@servidor.${domain}:2202/keyring.git
+    git add *
+    git commit -m "initial commit"
+    git push origin master
+
+Clone o repositório de configuração do puppet e registre uma nova hydra:
+
+    puppet_dir=~/projeto/puppet
+    git clone git://gitosis@servidor.${domain}:2202/puppet $puppet_dir
+    hydra projeto register $puppet_dir
+
+Gere novas chaves para os nós configurados e as envie para os nós:
+
+    hydra projeto newkeys
+    hydra projeto import servidor.pub
+
+
+## Partida do puppetmaster
+
+    /etc/init.d/puppetmaster start
+
+## Configuração de backups
+
+1. Backup local criptografado:
+    1. Criação de chaves GPG.
+    2. Configuração do backup local.
+2. Backup remoto:
+    1. Criação de chaves SSH para armazenamento remoto de backup.
+    2. Configuração do backup remoto.
+
+## Criação de outros vservers/nós
+
+* Nó de armazenamento ("storage") para agrupamento de backups.
+* Proxy.
+* Web.
+* Test.
+
+## Pedaços de código úteis para o bootstrap
+
+### Configuração de submódulos padrão
+
+    apt-get -y install puppetmaster puppet git-core openssh-server
+    cd /etc/puppet
+    mkdir modules
+    git init
+    git add .
+
+    repos="`lynx -dump http://git.sarava.org/?a=project_index | awk '{ print $1 }' | grep ^puppet-`"
+    for repo in $repos; do
+      module="`basename $repo .git | sed -e s/^puppet-//`"
+      if [ ! -d "modules/$module" ]; then
+        git submodule add git://git.sarava.org/puppet-$module.git modules/$module
+      fi
+    done
+
+No caso de bootstrap para um novo projeto, substitua as referências de `git.sarava.org` para `git.projeto.org`.
+
+### Configurando referências remotas em massa
+
+    # Configuracao
+    origin="sarava.org"
+    remotes="sarava.org:${port}"
+    repos="`lynx -dump http://git.$origin/?a=project_index | awk '{ print $1 }' | grep ^puppet-`"
+
+    # Adicionando referencias
+    for repo in $repos; do
+      module="`basename $repo .git | sed -e s/^puppet-//`"
+      if [ -d "puppet-$module" ]; then
+        cd puppet-$module
+        for remote in $remotes; do
+          ref="`echo $remote   | cut -d . -f 1`"
+          domain="`echo remote | cut -d : -f 1`"
+          port="`echo remote   | cut -d : -f 2`"
+          git remote add $ref ssh://gitosis@git.$domain:$port/puppet-$module.git
+          git push $ref master
+        done
+        cd ..
+      fi
+    done
+
+### Mudando referências em submódulos
+
+    # Configuracao
+    origin="sarava.org"
+    dest="exemplo.org"
+
+    cd puppet
+    sed -i -e "s/git.$origin/git.$dest/" .gitmodules
+    cd modules
+    for module in `ls`; do
+      cd $module
+      git remote rm origin
+      git remote add origin git://git.$dest/puppet-$module.git
+      git config branch.master.remote origin
+      git config branch.master.merge refs/heads/master
+      cd ..
+    done
+
+### Exemplo de criação em massa de módulos
+
+    # Configuracao
+    origin="sarava.org"
+    remotes="sarava.org:${port}"
+
+    mkdir puppet-{ikiwiki,moin,mysql,trac}/manifests -p
+    touch puppet-{ikiwiki,moin,mysql,trac}/manifests/init.pp
+    for module in ikiwiki moin mysql trac; do
+      cd puppet-$module
+      cp ../puppet-git/LICENSE .
+      git init
+      git add .
+      git commit -a -m "Initial import"
+      for remote in $remotes; do
+        ref="`echo $remote   | cut -d . -f 1`"
+        domain="`echo remote | cut -d : f 1`"
+        port="`echo remote   | cut -d : f 2`"
+        git remote add $ref ssh://gitosis@git.$domain:$port/puppet-$module.git
+        git push $ref master
+      done
+      cd ..
+    done
diff --git a/docs/boxes.md b/docs/boxes.md
new file mode 100644
index 0000000..dcd7550
--- /dev/null
+++ b/docs/boxes.md
@@ -0,0 +1,62 @@
+# Boxes
+
+## Necessidade
+
+* Ambiente de desenvolvimento ágil.
+* Que permita executar de forma isolada aplicações sem auditoria ou checagem de integridade.
+
+## Criando uma base box
+
+O procedimento básico já é detalhado aqui:
+
+* [Creating a Base Box - Vagrant Documentation](https://docs.vagrantup.com/v2/boxes/base.html).
+* [Creating a Base Box - VirtualBox Provider - Vagrant Documentation](https://docs.vagrantup.com/v2/virtualbox/boxes.html).
+
+Note que:
+
+* Você precisa apenas do pacote `virtualbox-guest-dkms` para que a integração da máquina com o vagrant funcione corretamente.
+* O procedimento não serve apenas para usar a máquina virtual com o vagrant. Você pode usá-la também diretamente com o VirtualBox.
+* A seguir apenas documentaremos configurações específicas ou melhorias em relação à documentação oficial do vagrant.
+
+### Configuração do sudo
+
+Usamos algo mais recomendado ao invés de mexer no `/etc/sudoers` do pacote:
+
+    echo "vagrant ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/vagrant
+    chown root.root /etc/sudoers.d/vagrant
+    chmod 0440 /etc/sudoers.d/vagrant
+
+### Workarounds
+
+A mensagem de erro [stdin: is not a tty](https://github.com/mitchellh/vagrant/issues/1673) é corrigida
+com isto no `/root/.profile`:
+
+    tty -s && mesg n
+
+### Customizando
+
+Você já pode parar por aí pois já tem uma máquina bem genérica ou começar a customizar
+a máquina para ter ferramentas e configurações comuns para o seu dia dia.
+
+Por exemplo, considere a [instalação](/install) da Hydra Suite na máquina virtual.
+
+## Encolhendo uma máquina virtual
+
+Procedimento genérico, dentro da máquina virtual:
+
+    hydractl upgrade clean
+    apt-get install zerofree # apenas uma vez
+    telinit 1
+    mount -o remount,ro /
+    zerofree /dev/sda1
+    halt
+
+No host (`$box` é o nome da máquina):
+
+    VBoxManage modifyhd --compact /var/cache/virtualbox/$box/$box.vdi
+
+# Referências
+
+* [How to compact VirtualBox's VDI file size?](https://superuser.com/questions/529149/how-to-compact-virtualboxs-vdi-file-size).
+* [Shrinking a Dynamic VirtualBox Disk Image](http://www.thelinuxdaily.com/2010/02/shrinking-a-dynamic-virtualbox-disk-image/).
+* [ubuntu - "mount: / is busy" when trying to mount as read-only so that I can run zerofree](https://unix.stackexchange.com/questions/42015/mount-is-busy-when-trying-to-mount-as-read-only-so-that-i-can-run-zerofree).
diff --git a/docs/certs.md b/docs/certs.md
new file mode 100644
index 0000000..9fc1a04
--- /dev/null
+++ b/docs/certs.md
@@ -0,0 +1,76 @@
+# Geração e renovação de certificados
+
+## Começando
+
+Proceda com a [configuração do ambiente de trabalho administrativo](/install).
+
+## Gerando novas chaves
+
+Proceda usando o [keyringer](https://keyringer.pw):
+
+    keyringer $HYDRA genpair ssl ssl/$DOMAIN *.$DOMAIN
+
+No caso da chave snakeoil (fornecida quando um atacante acessa https://IP), use
+
+    keyringer $HYDRA genpair ssl-self ssl/example.org example.org
+
+Chaves também podem ser geradas em massa. No caso de certificados simples (não-wildcard):
+
+    for domain in $DOMAINS; do
+      keyringer $HYDRA genpair ssl ssl/$domain $domain
+    done
+
+## Registrando mudancas parciais
+
+    keyringer $HYDRA git commit
+    keyringer $HYDRA git push
+
+## Comprando um certificado
+
+Em seguida, compre um certificado no registrar, envie a requisição de
+certificado (arquivo `CSR`) e proceda com a validação.
+
+## Após a renovação
+
+    cat /path/to/registrar.crt >> /path/to/$DOMAIN.crt
+    cat /path/to/$DOMAIN.crt    | keyringer $HYDRA encrypt ssl/$DOMAIN.crt
+
+    # Registrando e enviando mudancas finais
+    keyringer $HYDRA git commit
+    keyringer $HYDRA git push
+
+Informações de fingerprint:
+
+    openssl x509 -noout -text        -in /path/to/$DOMAIN.crt
+    openssl x509 -noout -fingerprint -in /path/to/$DOMAIN.crt
+    openssl x509 -noout -fingerprint -in /path/to/$DOMAIN.crt -md5
+
+Verificando os certificados assinados:
+
+    openssl verify -verbose -CAfile /path/to/registrar.crt /path/to/$DOMAIN.crt
+
+Comunicação ao público:
+
+  * [Modelo de mensagem](https://protocolos.fluxo.info/mensagens/certs/).
+  * Notificação para `https://www.$DOMAIN/pt-br/certs` dispínvel em `notices/certs*`.
+
+Assine as comunicações com a [chave do grupo](https://protocolos.fluxo.info/trac/wiki/Comunicacao/OpenPGP), por exemplo:
+
+    GPG_AGENT_INFO="" gpg -b --armor --default-key $KEY_FINGERPRINT -s $FOLDER/doc/notices/certs/$DOMAIN.pt-br.txt
+    GPG_AGENT_INFO="" gpg -b --armor --default-key $KEY_FINGERPRINT -s $FOLDER/doc/notices/certs/$DOMAIN.en.txt
+
+Copie as notificações para ser incluída em `https://$DOMAIN/certs`:
+
+    cp $FOLDER/doc/notices/certs/* $FOLDER/puppet/modules/site_apache/files/htdocs/$MAIN_DOMAIN/certs/
+    cd $FOLDER/puppet
+    git add modules/site_apache/files/htdocs/$DOMAIN/certs/
+    git commit -m "Atualizando info sobre certificados"
+    git push
+
+Por fim, atualize os `postfix::tlspolicy_snippet` do `$DOMAIN`, caso aplicável.
+
+## Instalando
+
+Para instalar o certificado num nodo:
+
+    hydra $HYDRA import-certs <nodename>
diff --git a/docs/cryptocalypse.md b/docs/cryptocalypse.md
new file mode 100644
index 0000000..2e97969
--- /dev/null
+++ b/docs/cryptocalypse.md
@@ -0,0 +1,84 @@
+# Cryptocalypse!
+
+Procedimento emergencial de rotação de chaves. Ou, como sobreviver a brechas do tipo [Heartbleed](http://heartbleed.com/)!
+
+## Começando
+
+Proceda com a [configuração do ambiente de trabalho administrativo](/install).
+
+## Atualizando
+
+Se for possível e desejável, faça upgrade geral
+
+    hydra $HYDRA mass-upgrade
+
+## Gerando novas chaves SSH
+
+Na máquina do/a administrador:
+
+    hydra $HYDRA newkeys all-ssh
+
+Para cada nodo usado no git público:
+
+    cp $FOLDER/puppet/keys/ssh/$nodo/"$nodo"_id_rsa.pub $FOLDER/git/public/keydir/root@$nodo.$DOMAIN.pub
+
+    ( cd $FOLDER/puppet     && git add . && git commit -m "Gerando chaves ssh" && git push )
+    ( cd $FOLDER/git/public && git add . && git commit -m "Gerando chaves ssh" && git push )
+
+## Chaves do Puppet
+
+[Reset da infra de CA do puppet](certs/puppet).
+
+## Certificados SSL
+
+[Gere novos certificados SSL](certs).
+
+## Chaves SSH dos ikiwikis
+
+    WIKIS="lista de ikiwikis"
+    NODE="aziz"
+
+    for wiki in $WIKIS; do
+      ssh-keygen -t rsa -P '' -b 4096 -f $FOLDER/puppet/keys/ssh/$NODE/ikiwiki/"$wiki"_id_rsa -C "$wiki@$wiki.$DOMAIN"
+      cp $FOLDER/puppet/keys/ssh/aziz/ikiwiki/"$wiki"_id_rsa.pub $FOLDER/git/public/keydir/$wiki@$wiki.$DOMAIN.pub
+    done
+
+    ( cd $FOLDER/puppet     && git add . && git commit -m "Gerando chaves para ikiwiki" && git push )
+    ( cd $FOLDER/git/public && git add . && git commit -m "Gerando chaves para ikiwiki" && git push )
+
+## Tor
+
+A parte fácil:
+
+    hydra $HYDRA mass-web /etc/init.d/tor stop
+    hydra $HYDRA mass-web rm -rf /var/lib/tor/hidden
+    hydra $HYDRA mass-web mkdir /var/lib/tor/hidden
+    hydra $HYDRA mass-web chown debian-tor. /var/lib/tor/hidden
+    hydra $HYDRA mass-web /etc/init.d/tor start
+
+Isso precisa ser feito manualmente para outros serviços (por exemplo email e ssh):
+
+    cd `hydra $HYDRA folder`/puppet
+    grep -R onion hiera
+    grep -R onion manifests
+    grep -R onion modules/site_*
+
+Monte uma lista de servidores e proceda com a regeneração:
+
+    SERVERS="galdino satanito magaiver"
+
+    for server in $SERVERS; do
+      hydra $HYDRA exec $server /etc/init.d/tor stop
+      hydra $HYDRA exec $server rm -rf /var/lib/tor/hidden
+      hydra $HYDRA exec $server mkdir /var/lib/tor/hidden
+      hydra $HYDRA exec $server chown debian-tor. /var/lib/tor/hidden
+      hydra $HYDRA exec $server /etc/init.d/tor start
+    done
+
+Em seguida, colete os novos hostnames e atualize os `ServerAlias` dos sites e outras referências:
+
+    hydra $HYDRA mass-web hydractl hidden-services
+
+## Senhas de usuário
+
+O procedimento deve variar de aplicação para aplicação. Por exemplo, para o drupal há o [Force password change](https://drupal.org/project/force_password_change).
diff --git a/docs/domains.md b/docs/domains.md
new file mode 100644
index 0000000..aeaea1d
--- /dev/null
+++ b/docs/domains.md
@@ -0,0 +1,15 @@
+# Gerenciamento de domínios
+
+## Começando
+
+Proceda com a [configuração do ambiente de trabalho administrativo](/install).
+
+## Checando expiração em massa
+
+Necessita o script [domain-check](https://git.sarava.org/?p=puppet-domain_check.git):
+
+    cd $FOLDER/puppet/modules/site_nginx/files
+
+    for file in *; do
+      domain-check -d $file
+    done
diff --git a/docs/firewall.md b/docs/firewall.md
new file mode 100644
index 0000000..37621ea
--- /dev/null
+++ b/docs/firewall.md
@@ -0,0 +1,80 @@
+# Configuração do shorewall 
+
+De início, instale o shorewall:
+
+    apt-get install shorewall
+
+É necessário que o iptables esteja configurado para encaminhar os pacotes de
+uma porta externa para os vservers. As seguinte diretiva precisa ser alterada
+na configuração original no arquivo `/etc/shorewall/shorewall.conf`:
+
+    IP_FORWARDING=Yes
+
+O arquivo `/etc/shorewall/interfaces` deve conter a interface de rede:
+
+    #ZONE   INTERFACE       BROADCAST       OPTIONS
+    - eth0 detect tcpflags,blacklist,routefilter,nosmurfs,logmartians,norfc1918
+    #LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE
+
+O arquivo `/etc/shorewall/zones` deve conter as zonas da rede:
+
+    ###############################################################################
+    #ZONE   TYPE            OPTIONS         IN                      OUT
+    #                                       OPTIONS                 OPTIONS
+    fw      firewall
+    vm      ipv4
+    net     ipv4
+    #LAST LINE - ADD YOUR ENTRIES ABOVE THIS ONE - DO NOT REMOVE
+
+O arquivo `/etc/shorewall/hosts` associa zonas a subredes:
+
+    #ZONE   HOST(S)                                 OPTIONS
+    vm      eth0:192.168.0.0/24
+    net     eth0:0.0.0.0/0
+    #LAST LINE -- ADD YOUR ENTRIES BEFORE THIS LINE -- DO NOT REMOVE
+
+O arquivo `/etc/shorewall/policy` define as regras para tráfego de pacotes:
+
+    ###############################################################################
+    #SOURCE         DEST            POLICY          LOG             LIMIT:BURST
+    #                                               LEVEL
+    vm              net             ACCEPT
+    $FW             net             ACCEPT
+    $FW             vm              ACCEPT
+    net             all             DROP            info
+    # THE FOLLOWING POLICY MUST BE LAST
+    all             all             REJECT          info
+    #LAST LINE -- DO NOT REMOVE
+
+E o arquivo `/etc/shorewall/rules` define exceções às regras gerais:
+
+    ################################################################
+    #ACTION         SOURCE          DEST            PROTO   DEST
+    SSH/ACCEPT      net             $FW
+    Ping/ACCEPT     net             $FW
+    HTTP/ACCEPT     net             $FW
+    HTTPS/ACCEPT    net             $FW
+    #LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE
+
+Adicionamos máscaras NAT aos pacotes da rede interna através do `/etc/shorewall/masq`:
+
+    ###############################################################################
+    #INTERFACE              SOURCE          ADDRESS         PROTO   PORT(S) IPSEC   MARK
+    eth0:!192.168.0.0/24    192.168.0.0/24
+    #LAST LINE -- ADD YOUR ENTRIES ABOVE THIS LINE -- DO NOT REMOVE
+
+Habilite o shorewall mudando o valor de startup de `/etc/default/shorewall` para `1`:
+
+    startup=1
+
+Finalmente podemos ligar o shorewall:
+
+    /etc/init.d/shorewall start
+
+## Shorewall e Puppet 
+
+Uma vez que um nodo [puppetmaster](../puppet) estiver rodando, o módulo
+[puppet-shorewall](http://git.sarava.org/?p=puppet-shorewall.git;a=summary)
+poderá ser utilizado para gerenciar o firewall. No entanto, se você for
+substituir o presente procedimento pela sua versão via puppet, certifique-se de
+apagar os arquivos `/etc/shorewall/{masq,policy,zones,rules,interfaces}`. 
diff --git a/docs/firewire.md b/docs/firewire.md
new file mode 100644
index 0000000..ad80bc9
--- /dev/null
+++ b/docs/firewire.md
@@ -0,0 +1,23 @@
+# Firewire
+
+Para evitar [dumps de memória via
+firewire](http://links.sarava.org/tags/firewire), [este
+artigo](http://www.hermann-uwe.de/blog/physical-memory-attacks-via-firewire-dma-part-1-overview-and-mitigation)
+oferece a mitigação ideal via `/etc/modprobe.d/blacklist`:
+
+    # Physical memory attacks via Firewire/DMA Mitigation
+    # Prevent automatic loading of the ohci1394 module.
+    blacklist ohci1394
+    # Prevent manual loading of the ohci1394 module.
+    install ohci1394 false
+    # Iff we should ever load the ohci1394 module, force the use of the 'phys_dma=0' option.
+    options ohci1394 phys_dma=0
+
+Depois dessa configuração, é preciso atualizar a `initrd` de cada sistema, através do comando
+
+    update-initramfs -v -u
+
+Feito isso, o firewire pode ser desabilitado nos sistemas que estão rodando simplesmente com um
+
+    rmmod ohci1394
+
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..4c18930
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,40 @@
+# Padrão Fluxo
+
+O Padrão Fluxo é uma sistematização de configuração de servidores,
+gerenciadores de conteúdo e aplicações diversas usados pelo Grupo Fluxo. O
+padrão foi desenvolvido para:
+
+* Ter controle dos pacotes utilizados, arquivos de configuração e serviços em
+  uso.
+* Uniformidade de administração.
+* Sistema de gerenciamento de backups comum para que as máquinas de um projeto
+  possam trocar dados.
+* Que um servidor seja configurado apenas uma vez e que suas configurações
+  possam ser aproveitados para outras máquinas.
+* Que sites e serviços sejam armazenados de maneira regular para facilitar
+  atualizações e migrações.
+* Manter projetos e serviços isolados uns dos outros através de servidores
+  virtuais.
+* Tornar a instalação dos servidores facilmente replicável.
+
+### Licença
+
+O Padrão Fluxo é distribuído conforme a [GNU Affero General Public
+License](http://www.gnu.org/licenses/agpl-3.0.html):
+
+    Fluxo Pattern
+    Copyright (C) 2015      Fluxo  Group
+    Copyright (C) 2009-2015 Sarava Group
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as
+    published by the Free Software Foundation, either version 3 of the
+    License, or any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
diff --git a/docs/install.md b/docs/install.md
new file mode 100644
index 0000000..508649a
--- /dev/null
+++ b/docs/install.md
@@ -0,0 +1,28 @@
+# Instalação da Hydra Suite
+
+Atualmente o Padrão Saravá utiliza a [Hydra
+Suite](http://git.sarava.org/?p=hydra.git;a=summary) para fazer o
+provisionamento. Versões anteriores deste documento não o utilizam, são mais
+descritivas e talvez até mais interessantes ao público interessado nos
+pormenores do procedimento de instalação.
+
+A Hydra Suite pode ser obtida e instalada diretamente do seu repositório:
+
+    git clone --recursive git://git.sarava.org/hydra.git
+
+Verifique a [integridade do código](https://manual.sarava.org/specs/code/):
+
+    cd hydra
+    tag="`git describe --abbrev=0 --tags`"
+    git tag -v $tag && git checkout $tag
+
+Opcionalmente instale a suite no sistema:
+
+    ./hydractl install
+
+## Ambiente de trabalho administrativo
+
+    HYDRA="nome-do-grupo"
+    FOLDER="`hydra $HYDRA folder`"
+    MAIN_DOMAIN="`hydra $HYDRA config domain`"
+    DOMAIN="$MAIN_DOMAIN" # ou outro domínio
diff --git a/docs/keys.md b/docs/keys.md
new file mode 100644
index 0000000..a708afb
--- /dev/null
+++ b/docs/keys.md
@@ -0,0 +1,150 @@
+# Chaves
+
+## Repositório de chaves
+
+### Configuração
+
+A maior parte dos procedimentos a seguir depende do aplicativo
+[keyringer](http://git.fluxo.info/?p=keyringer.git;a=summary), da [Hydra
+Suite](http://git.fluxo.info/?p=hydra.git;a=summary) e de uma configuração do
+tipo
+
+Proceda então com a [configuração do ambiente de trabalho administrativo](/install).
+
+### Inicializando um repositório
+
+    # Inicializando
+    keyringer $HYDRA init $FOLDER/conf/keyring
+
+### Gerando chaves https
+
+Gerar chaves e certificados SSL auto-assinados é simples:
+
+    # Gerando chaves para https
+    keyringer $HYDRA genpair ssl-self ssl/$DOMAIN $DOMAIN
+
+Caso você queira gerar apenas a chave e a requisição de certificação (CSR), use
+
+    keyringer $HYDRA genpair ssl ssl/$DOMAIN $DOMAIN
+
+Para a chaves e requisições CaCert, use
+
+    keyringer $HYDRA genpair ssl-cacert ssl/$DOMAIN $DOMAIN
+
+### Gerando chaves para novos nodos
+
+    # Gerando chaves ssh e gpg para novos nodos
+    # A importacao das chaves gpg nos nodos deve ser feita manualmente
+    hydra $HYDRA newkeys
+
+### Submetendo mudanças
+
+    # Submetendo
+    keyringer $HYDRA git remote add origin giolite@admin.$DOMAIN:keyring.git
+    keyringer $HYDRA git push origin master
+
+### Importação de chaves GPG
+
+Importando chaves nos seus respectivos nodos:
+
+    hydra $HYDRA import-key
+
+## Chaves SSH
+
+Para gerar uma chave SSH pessoal, use um comando do tipo
+
+    ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa     -C "seu@email"
+    ssh-keygen -t ed25519     -f ~/.ssh/id_ed25519 -C "seu@email"
+
+Esse tipo de comando irá gerar uma **chave privada** em `~/.ssh/id_rsa` e uma
+respectiva **chave pública** em `~/.ssh/id_rsa.pub`. Se você já possui uma
+chave em `~/.ssh/id_rsa` e quiser mantê-la, escolha outro nome para a nova
+chave, como por exemplo `~/.ssh/id_rsa_aplicacao`.
+
+## Senhas
+
+Exemplo de geração de senhas usando o [pwgen](http://packages.debian.org/lenny/pwgen):
+
+    pwgen -s -y 25
+
+Atenção: muitos programas e configurações podem não funcionar por conta do uso
+de caracteres especiais nas senhas. Assim, recomenda-se evitar alguns
+caracteres especiais -- por exemplo delimitadores de campo -- quando for o caso
+e/ou testar a senha após a sua escolha.
+
+## Impressões digitais
+
+### Chaves SSL
+
+Chaves SSL podem ter seu fingerprint determinado através usando o [OpenSSL em
+linha de comando](http://www.madboa.com/geek/openssl), com linhas do tipo
+
+    openssl x509 -noout -in /etc/ssl/certs/cert.crt -fingerprint
+    openssl x509 -noout -in /etc/ssl/certs/cert.crt -fingerprint -md5
+
+### Chaves públicas SSH
+
+O seguinte comando retorna todas as fingerprints dos arquivos de chave pública ssh terminados em `.pub` no diretório `/etc/ssh/`:
+
+    hydractl ssh-finger
+
+Para obter um fingerprint salvo no seu `~/.ssh/known_hosts` pessoal, use
+
+    ssh-keygen -l -F  servidor.exemplo.org        -f ~/.ssh/known_hosts
+    ssh-keygen -l -F [servidor.exemplo.org]:porta -f ~/.ssh/known_hosts
+
+## Monkeysphere
+
+O [monkeysphere](http://web.monkeysphere.info) é um programa que permite a
+verificação de hosts SSH e usuários/as através da Teia de Confiabilidade do
+OpenPGP. Com ele, o gerenciamento de fingerprints fica mais fácil e evita que
+páginas como esta centralizem informações que possam se desatualizar.
+
+Além dos [usos já documentados](http://web.monkeysphere.info/doc/), o
+monkeysphere pode ser utilizado também para autenticação em sistemas que não
+possuem tal suporte:
+
+    monkeysphere gen-subkey -l 4096                      # caso voce ainda nao tenha uma chave
+    mkdir -m 700 ~/.monkeysphere
+    echo "SEU-ID" >> ~/.monkeysphere/authorized_user_ids # exemplo: "Seu Nome <seu-email@example.org>"
+    touch ~/.ssh/id_rsa_monkeysphere.pub
+    chmod 600 ~/.ssh/id_rsa_monkeysphere.pub
+    MONKEYSPHERE_AUTHORIZED_KEYS=$HOME/.ssh/id_rsa_monkeysphere.pub monkeysphere update-authorized_keys
+
+Agora, basta fornecer a chave localizada em `~/.ssh/id_rsa_monkeysphere.pub` para autenticação :)
+
+## Hashes
+
+Hashes são úteis para o armazenamento de senhas de usuário. São usados por
+exemplo no `shadow(5)`. Para gerar um hash compatível com o shadow (por exemplo
+para gestão via
+[puppet-user](http://git.fluxo.info/?p=puppet-user.git;a=summary)), utilize o
+seguinte comando disponível no pacote [whois do
+Debian](https://packages.debian.org/stable/whois):
+
+    mkpasswd -m sha-256
+
+Hashes para `htpasswd` são descritos [aqui](http://sarava.fluxo.info/Ajuda/ProtegendoConteudo).
+
+## Exportação de assinaturas locais
+
+    gpg --armor --export-options export-local-sigs --export KEYID
+
+## Forçando entrada de senhas via console no GnuPG
+
+    DISPLAY="" gpg <opcoes>
+
+## Mudando senhas de chaves
+
+    ssh-keygen -p -f ~/.ssh/id_rsa
+    gpg --edit-key <ID> edit-key passwd
+
+## Chave OpenPGP de Coletivo
+
+Vide [Chave OpenPGP de Coletivo](role).
+
+## Referências
+
+* [Using ssh-agent with ssh](http://mah.everybody.org/docs/ssh).
+* [Using Rsync and SSH ](http://troy.jdmz.net/rsync/index.html).
+* [SSH and ssh-agent](http://www.securityfocus.com/infocus/1812).
diff --git a/docs/keys/role.md b/docs/keys/role.md
new file mode 100644
index 0000000..6c29f32
--- /dev/null
+++ b/docs/keys/role.md
@@ -0,0 +1,20 @@
+# Role key
+
+## Começando
+
+    KEY="fingerprint da chave OpenPGP"
+
+## Procedimento para criar as assinaturas
+
+    GPG_AGENT_INFO="" gpg -b --armor --default-key "$KEY" -s openpgp.txt
+
+## Renovação
+
+    GPG_AGENT_INFO="" gpg --edit-key "$KEY"
+    gpg --armor --export-secret-keys "$KEY" | keyringer $HYDRA encrypt $DOMAIN/contato/gpg/key.asc
+    gpg --armor --export             "$KEY" | keyringer $HYDRA encrypt $DOMAIN/contato/gpg/key.pub.asc
+
+    keyringer $HYDRA git commit
+    keyringer $HYDRA git push
+
+    gpg --send-key "$KEY"
diff --git a/docs/nodo.md b/docs/nodo.md
new file mode 100644
index 0000000..77bbd85
--- /dev/null
+++ b/docs/nodo.md
@@ -0,0 +1,162 @@
+# Gestão de nodos
+
+## Adicionando um nodo 
+
+Procedimento para adicionar um novo nodo à infraestrutura.
+
+### Assumindo
+
+Neste exemplo, assumiremos os seguites parâmetros:
+
+    node=novo-host       # hostname do novo nodo
+    hydra=nome-do-grupo  # nome da hydra
+    domain="example.org" # dominio do projeto
+
+Ainda:
+
+* `admin@box$`: indica shell da máquina do/a administrador.
+* `root@nodo#`: indica o shell do novo nodo.
+* `root@master#`: indica o shell do master.
+
+Certifique-se de configurar os parâmetros acima em cada um dos shells mencionados.
+
+### Configuração de DNS
+
+O primeiro passo é criar uma entrade de DNS para o novo nodo. Use uma das
+seguintes configurações na interface de atualização de DNS, substituindo
+`$node`, `$ip` ou `$domain` pelos valores apropriados.
+
+No caso de um registro `A`:
+
+    $node 3600 IN A $ip
+
+No caso de um `CNAME`:
+
+    $node 3600 IN CNAME $domain.
+
+### Provisionamento
+
+Esta consiste na criação do nodo -- máquina virtual ou servidor físico, podendo
+ser feita de dois modos:
+
+* Via puppet na própria infraestrutura da `$hydra`.
+  * No caso de um servidor físico, proceda [apropriadamente](/install).
+  * No caso de uma máquina virtual, defina-a no manifest do puppet da máquina
+    hospedeira usando o padrão de virtualização desejado.
+* Solicitando a um coletivo hospedeiro altamente confiável.
+
+No caso de uma máquina virtual hospedada numa máquina física do grupo,
+considere a [faixa de alocação](allocation) de IPS.
+
+### Definição do nodo
+
+Definição básica do nodo:
+
+    admin@box$ hydra $hydra newnode $node # cria definicoes minimas para o nodo
+    admin@box$ hydra $hydra newkeys $node # criar as chaves necessarias para o nodo
+
+Após esses comandos, é preciso editar o arquivo `puppet/hiera/production/domain/$domain/$node.$domain.yaml`
+e ajustar configurações básicas de chaves, senhas, etc.
+
+Em seguida, submeta as mudanças para o repositório:
+
+    admin@box$ cd `hydra $hydra folder`/puppet
+    admin@box$ git commit -a -m "Adicionando nodo $node" && git push
+
+### Chaves
+
+Envie a chaves geradas para o novo nodo:
+
+    admin@box$ hydra $hydra import-keys $node.$domain
+
+No caso de chaves para conexões TLS, envie-as juntamente com o certificado de
+cada domínio:
+
+    admin@box$ hydra $hydra import-certs $node.$domain [certs]
+
+### Configurando o puppet
+
+Instale o pacote:
+
+    root@nodo# apt-get install puppet
+
+Certifique-se então que os seguintes valores correspondem a `$node.$domain`:
+
+    root@nodo# facter fqdn
+
+Lembre-se de iniciar o `puppet agent` pela primeira vez através de um comando
+do tipo
+
+    root@nodo# puppet agent --server puppet.`facter domain` --pluginsync true --waitforcert 60 --test
+
+No caso de uma porta fora do padrão, use o parâmetro `--masterport`. Em
+seguida, verifique se os fingerprints dos certificados (master e nodo)
+coincidem. No master:
+
+    root@master# puppet cert list | grep $node.$domain
+
+Caso os fingerprints batam, basta liberar o novo nodo a partir do host em que
+roda o master como o comando
+
+    root@master# puppet cert sign $node.$domain
+
+Assista as mudanças nos arquivos de log (`/var/log/daemon.log` ou
+`/var/log/syslog`):
+
+    root@nodo# tail -F /var/log/daemon.log /var/log/syslog
+
+Mais detalhes
+[aqui](http://projects.puppetlabs.com/projects/1/wiki/certificates_and_security)
+sobre certificados e segurança.
+
+### Deploy da Hydra Suite
+
+Faça a instalação da hidra suite no novo nodo:
+
+    admin@box$ hydra $hydra install $node.$domain
+
+### Fingerprints e Monkeysphere
+
+Verifique os fingerprints do SSH e do puppet:
+
+    root@nodo#   hydractl ssh-finger
+    root@nodo#   hydractl puppet-finger
+    root@master# hydractl puppet-finger
+
+Opcionalmente, proceda com a [configuração das chaves de serviço do
+monkeysphere](http://web.monkeysphere.info/doc/host-keys).
+
+### Inscrição em lista de mensagens
+
+Caso o alias de email para `root` esteja configurado para o endereço de uma
+lista de discussão privada de email (o que permite um grupo de
+administradores/as monitorarem mensagens de sistema), certifique-se de
+configurar os endereços de `root@$node.$domain` e demais endereços como
+assinantes da lista no modo `no mail` (sem recebimento). Assim, eles poderão
+enviar mensagens mas não receberão nenhuma mensagem da lista.
+
+## Retirando um nodo
+
+Para descomissionar um nodo, proceda na máquina administrativa:
+
+    admin@box$ hydra $hydra sync
+    admin@box$ cd hydra $hydra folder
+    admin@box$ find -name "$node*" -exec rm {} \;
+    admin@box$ $EDITOR manifests/nodes.pp # remova a linha de inclusao do nodo
+    admin@box$ git status                 # revisao
+    admin@box$ git commit -a -m "Descomissionando $node"
+    admin@box$ git push
+
+Em seguida, no nodo master:
+
+    root@master# puppet cert clean $node.$domain
+    root@master# hydractl puppet-clean-stored $node.domain
+
+Por fim:
+
+* Checar backups remoto do nodo, caso se queira recuperar algum dado no futuro!
+* Apagar entradas DNS.
+* Chaves no keyringer não precisam ser movidas necessariamente, pois podem ser
+  úteis para acesso dos backups.
+* Limpar página de fingerprints.
+* Revogar chaves (OpenPGP, SSL), quando cabível.
diff --git a/docs/nodo/allocation.md b/docs/nodo/allocation.md
new file mode 100644
index 0000000..ff4c368
--- /dev/null
+++ b/docs/nodo/allocation.md
@@ -0,0 +1,41 @@
+# Alocação de IPs e contextos
+
+Convenção de contextos, portas e IPs externos de acordo com a classe/uso das
+máquinas virtuais.
+
+Nela, são alocados os `X` primeiros contextos de cada máquina física pras classes
+próprias, usando os números altos (faixa `Y`) para máquinas virtuais de
+terceiros.
+
+No caso:
+
+    || Contexto || Classe  ||
+    || 1        || server  ||
+    || 2        || master  ||
+    || 3        || proxy   ||
+    || 4        || storage ||
+    || 5        || mail    ||
+    || 6        || web     ||
+    || 7        || dns     ||
+    || 8        || jabber  ||
+    || 9        || test    ||
+    || 10       || mumble  ||
+
+Assim,
+
+* Alocamos até o contexto 40 para uso próprio.
+* Do 41 ao 99 para máquinas virtuais de terceiros, ou outros valores nessa
+  mesma linha.
+
+Eventualmente, da faixa Y (41 ao 99, por exemplo) podemos alocar um numero
+universal por grupo hospedado. Assim,
+
+* 41 seria sempre grupo X.
+* 42 grupo Y, etc.
+
+Ou seja,
+
+ * Sempre que houvesse uma máquina virtual do grupo Y numa maquina, seria
+   sempre no contexto 42, IP interno 192.168.0.42, porta 2242.
+ * Já o nome da máquina virtual mudaria sempre, eventualmente seguindo o padrao
+   do [puppet-bootstrap](https://git.sarava.org/?p=puppet-bootstrap.git).
diff --git a/docs/provision.md b/docs/provision.md
new file mode 100644
index 0000000..228452d
--- /dev/null
+++ b/docs/provision.md
@@ -0,0 +1,52 @@
+# Provisionando um Sistema Operacional
+
+A seguir, o procedimento de instalação de um sistema com disco criptografado,
+opcionalmente com gerenciamento de partida via dispositivo de armazenamento
+USB.
+
+## Instalação 
+
+Após a [instalação da Hydra Suite](/install), basta iniciar o procedimento com
+os devidos privilégios administrativos (como `root` ou usando o `sudo`):
+
+    hydractl provision
+
+O programa perguntará por parâmetros da instalação, como o dispositivo no qual
+o deve ser instalado, a arquitetura, a versão do sistema e o domínio principal.
+Depois disso a suíte se encarregará da maior parte dos detalhes de instalação.
+
+## Continuando remotamente 
+
+Agora a máquina já está quase a ponto de poder ser administrada remotamente.
+Antes disso, configure a rede e adicione as contas de usuário/a iniciais:
+
+    vi /etc/network/interfaces.d/local              # configuracao de rede
+    vi /etc/udev/rules.d/70-persistent-net.rules    # ajuste das placas de rede
+    vi /etc/resolv.conf                             # para usar o dns disponivel no data center
+    adduser nome-de-usuario
+
+Antes de largar a máquina no data center, lembre-se de anotar os fingerprints
+do ssh exibidos anteriormente.
+
+## Expansão de espaço em disco 
+
+* [How to resize a LUKS-encrypted partition created over LVM2](http://www.saout.de/tikiwiki/tiki-index.php?page=ResizeLUKSPartitions).
+* [Resizing Encrypted Filesystems](http://www.debian-administration.org/articles/536).
+* [Resizing a dm-crypt / LVM / ext3 partition](http://www.hermann-uwe.de/blog/resizing-a-dm-crypt-lvm-ext3-partition). 
+
+## Referências 
+
+Algumas referências para instalação:
+
+* [Encrypted Root LVM](http://www.howtoforge.com/encrypted-root-lvm).
+* [Encrypted filesystem - rigacci.org](http://www.rigacci.org/wiki/doku.php/doc/appunti/linux/sa/cryptfs).
+* [EncryptedFilesystems - Ubuntu Documentation](https://help.ubuntu.com/community/EncryptedFilesystems).
+* [Encrypting an entire system - ArchWiki](https://wiki.archlinux.org/index.php/Dm-crypt/Encrypting_an_entire_system#LUKS_on_LVM).
+
+A opção de partida `rootdelay` é importante no caso de sistemas contidos dentro
+de volumes USB, já que o kernel demora alguns instantes para detectar tais
+volumes. Detalhes a respeito em
+
+* [Installing Linux on USB - Part 5: Installing Debian Linux on USB flash memory drives](http://blogs.koolwal.net/2009/02/03/installing-linux-on-usb-part-5-installing-debian-linux-on-usb-flash-memory-drives/).
+* [initramfs-tools: lvm is not initialized on USB disks](http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=366175#37).
+* [When root on USB: add rootdelay=xx to kernel command line](https://blueprints.launchpad.net/ubuntu/+spec/kernel-boot-usb-roodelay).
diff --git a/docs/rescue.md b/docs/rescue.md
new file mode 100644
index 0000000..95ffe03
--- /dev/null
+++ b/docs/rescue.md
@@ -0,0 +1,67 @@
+# Sistema de Resgate
+
+Um sistema de resgate pode ser útil para a [instalação](install.md) de um sistema
+novo ou mesmo para a manutenção de máquinas com defeito.
+
+## Baixando o sistema
+
+Utilizamos imagens `iso-hybrid` do [Debian
+Live](https://www.debian.org/CD/live/) como base para o sistema de resgate.
+
+## Gravando o sistema
+
+    dd if=debian-live-6.0.1-amd64-standard.iso of=/dev/sdb
+
+## Criando uma imagem de resgate
+
+Imagens de resgate podem ser criadas usando o
+[debirf](http://cmrg.fifthhorseman.net/wiki/debirf):
+
+    apt install debirf
+    tar xzf /usr/share/doc/debirf/example-profiles/rescue.tgz 
+    debirf make rescue
+    debirf makeiso rescue
+
+Alternativamente, podemos criá-las usando o
+[live-build](http://live.debian.net/devel/live-build/):
+
+    apt install live-build
+    mkdir live-default && cd live-default
+    lb config
+    sudo lb build
+
+Mais informações
+[aqui](http://live.debian.net/manual/git/html/live-manual.en.html),
+especialmente sobre [criação de
+imagens](http://live.debian.net/manual/git/html/live-manual.en.html#179) e
+[customização de versão e
+pacotes](http://live.debian.net/manual/git/html/live-manual.en.html#managing-a-configuration).
+
+## Habilitando acesso remoto
+
+    apt install openssh-server
+    ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key.pub
+
+## Configuração mínima
+
+    sudo su
+    passwd root
+
+## Instalando ferramentas básicas
+
+    apt update
+    apt install screen pciutils usbutils git locales
+
+## Usando remotamente
+
+A grande vantagem do sistema de resgate é a sua possibilidade de utilização
+remota. Com o servidor `SSH` instalado, é possível se conectar a ele do
+conforto do seu desktop ou laptop! Antes de fazer isso, não deixe de verificar
+a impressão digital do serviço `SSH` do sistema de resgate.
+
+A partir do seu computador:
+
+    ssh root@IP-DO-SISTEMA-DE-RESGATE
+    # confirme o fingerprint   
+
+Uma vez no sistema, é até possível compartilhar a sessão de trabalho usando o `screen`.
diff --git a/docs/swap.md b/docs/swap.md
new file mode 100644
index 0000000..9004f47
--- /dev/null
+++ b/docs/swap.md
@@ -0,0 +1,37 @@
+# Swap criptografada no Debian 
+
+Se, no caso de partições de sistemas de arquivos é interessante que sejam
+montadas apenas por intervenção humana (pois do contrário não haverá ganho em
+segurança com a criptografia), o mesmo não precisa ocorrer com a swap porque
+ela é usada apenas como área de troca temporária, mas apenas se a mesma foi
+sempre recriada com uma chave aleatória.
+
+Por isso, não há problema em deixar o sistema recriar uma swap criptografada
+com chave aleatória a cada vez que o sistema é reiniciado. Isso é até uma
+vantagem, já que, a cada vez que o sistema reinicia, ele usa uma chave
+diferente para criar a swap.
+
+O procedimento a seguir é baseado em [Encrypted swap partition on
+Debian/Ubuntu](http://feeding.cloud.geek.nz/2008/03/encrypted-swap-partition-on.html).
+
+## Procedimento 
+
+Considerando que você esteja com o pacote `cryptsetup` instalado, proceda da
+seguinte maneira para a criação de um dispositivo de swap:
+
+    swapoff -a
+    cryptsetup -h sha512 -c aes-xts-plain64:sha256 -s 512 create swap /dev/SUA_SWAP
+    mkswap -f /dev/mapper/swap
+    swapon /dev/mapper/swap
+
+Adicione a seguinte entrada no seu `/etc/crypttab`:
+
+    swap /dev/SUA_SWAP /dev/random swap,cipher=aes-xts-plain64:sha256
+
+Substitua a entrada atual para a swap do `/etc/fstab` para a seguinte:
+
+    /dev/mapper/swap none swap sw 0 0
+
+Proceda de modo análogo para cada swap existente no sistema. Ao reiniciar sua
+máquina, o sistema deverá ser capaz de recriar os dispositivos de swap usando
+uma nova senha aleatória a cada vez. 
diff --git a/docs/todo.md b/docs/todo.md
new file mode 100644
index 0000000..17f00d2
--- /dev/null
+++ b/docs/todo.md
@@ -0,0 +1,12 @@
+# TODO
+
+## [Certificados](certs.md)
+
+* Disponinibilizar modelos (`templates/certs` e `notices/certs`).
+* Procedimento para salvar contratos, invoices, etc no repositório de
+  documentação.
+* Onde for possível, substituir "SSL" por "TLS", "x509", "certs" ou
+  "Certificados" quando aplicável.
+* Traduzir
+  [Certificates](https://help.riseup.net/pt/security/network-security/certificates)
+e usar como referência de protocolo.