Feat: migrate docs from Ikiwiki to MkDocs

5 files changed, 402 insertions, 0 deletions

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