runv-server

commit e357e9361dee0c77ae3ee7f149c5252f31f8195f
parent 0a611e81c275272cb504994c095ce543e0fb8d53
Author: Pablo Murad <pblmrd@gmail.com>
Date:   Sat, 16 May 2026 15:50:32 -0300

+ docs

Diffstat:
M
docs/13-troubleshooting.md
 | 
2
+-
A
docs/16-repair-users.md
 | 
106
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
M
docs/README.md
 | 
4
+++-
M
docs/admin.md
 | 
2
++

4 files changed, 112 insertions(+), 2 deletions(-)
diff --git a/docs/13-troubleshooting.md b/docs/13-troubleshooting.md
@@ -23,7 +23,7 @@ sudo python3 REPO/scripts/admin/repair_user.py --user USER --dry-run --verbose
 sudo python3 REPO/scripts/admin/repair_user.py --user USER
 ```
 
-- O reparador também corrige `~` para `755`, cria `.ssh`, `public_html`, `public_gopher`, `public_gemini` se faltarem, e cria modelos ausentes de `index.html`, `gophermap` e `index.gmi`.
+- O reparador também corrige `~` para `755`, cria `.ssh`, `public_html`, `public_gopher`, `public_gemini` se faltarem, e cria modelos ausentes de `index.html`, `gophermap` e `index.gmi`. Ver [16-repair-users.md](16-repair-users.md).
 
 ## Email não envia (entre / Mailgun)
 
diff --git a/docs/16-repair-users.md b/docs/16-repair-users.md
@@ -0,0 +1,106 @@
+# Reparar usuários
+
+[← Índice](README.md)
+
+Use esta página quando um membro existe no sistema, mas a home ficou incompleta ou com permissões erradas. Sintomas comuns:
+
+- `https://runv.club/~USER/` mostra `Index of /~USER`;
+- falta `~/public_html/index.html`;
+- faltam `~/public_gopher/gophermap` ou `~/public_gemini/index.gmi`;
+- a home está com dono `root:root` após remoção de jail antiga;
+- o provisionamento foi interrompido depois do `adduser`.
+
+## Ferramenta canônica
+
+O reparador é:
+
+```bash
+sudo python3 REPO/scripts/admin/repair_user.py --help
+```
+
+Ele é conservador:
+
+- cria apenas diretórios e arquivos esperados quando estão ausentes;
+- não sobrescreve `index.html`, `gophermap` ou `index.gmi` existentes;
+- corrige dono e modo da home e dos artefatos padrão;
+- não faz `chown -R`;
+- não toca em `/var/vmail`, Dovecot, Roundcube, Maildir ou qualquer parte do email.
+
+## Reparar um usuário
+
+Sempre comece com `--dry-run`:
+
+```bash
+cd /opt/runv-server
+sudo python3 scripts/admin/repair_user.py --user USER --dry-run --verbose
+```
+
+Se o plano estiver correto:
+
+```bash
+sudo python3 scripts/admin/repair_user.py --user USER
+```
+
+O script garante:
+
+| Caminho | Modo | Dono |
+|---------|------|------|
+| `/home/USER` | `755` | `USER:USER` |
+| `/home/USER/.ssh` | `700` | `USER:USER` |
+| `/home/USER/.ssh/authorized_keys`, se existir | `600` | `USER:USER` |
+| `/home/USER/public_html` | `755` | `USER:USER` |
+| `/home/USER/public_html/index.html` | `644` | `USER:USER` |
+| `/home/USER/public_gopher` | `755` | `USER:USER` |
+| `/home/USER/public_gopher/gophermap` | `644` | `USER:USER` |
+| `/home/USER/public_gemini` | `755` | `USER:USER` |
+| `/home/USER/public_gemini/index.gmi` | `644` | `USER:USER` |
+
+Se `authorized_keys` estiver ausente, o script avisa e não cria uma chave falsa. A chave pública precisa ser recuperada do pedido original ou instalada por outro fluxo administrativo.
+
+## Reparar todos os candidatos
+
+Para verificar usuários de `/var/lib/runv/users.json` e contas candidatas em `/home`:
+
+```bash
+sudo python3 scripts/admin/repair_user.py --all-users --dry-run --verbose
+```
+
+Para aplicar:
+
+```bash
+sudo python3 scripts/admin/repair_user.py --all-users
+```
+
+O modo `--all-users` ignora contas reservadas como `root`, `entre`, `pmurad-admin`, `www-data` e `vmail`.
+
+## Validação
+
+Depois do reparo:
+
+```bash
+sudo ls -la /home/USER
+sudo ls -la /home/USER/public_html
+curl -I https://runv.club/~USER/
+```
+
+O navegador deve deixar de mostrar `Index of /~USER` quando `public_html/index.html` existir. Se o Apache ainda listar o diretório, confirme:
+
+```bash
+sudo stat /home/USER /home/USER/public_html /home/USER/public_html/index.html
+sudo journalctl -u apache2 --since "10 minutes ago"
+```
+
+## Quando não usar
+
+Não use `repair_user.py` para:
+
+- trocar chave SSH;
+- recriar usuário removido;
+- corrigir quota;
+- reparar email local;
+- mexer em `/var/vmail`;
+- refazer jail SSH legada.
+
+Para chave SSH, use o fluxo de atualização de usuário. Para quota, use `create_runv_user.py` / `update_user.py` conforme o caso. Para email local, preserve a regra operacional: o RunV não deve alterar permissões de `/var/vmail`.
+
+Próximo: [Glossário e referência](15-glossary-and-reference.md).
diff --git a/docs/README.md b/docs/README.md
@@ -19,7 +19,8 @@
 13. [Segurança e privacidade](12-security-and-privacy.md)
 14. [Resolução de problemas](13-troubleshooting.md)
 15. [Smoke tests](14-smoke-tests-and-validation.md)
-16. [Glossário e referência](15-glossary-and-reference.md)
+16. [Reparar usuários](16-repair-users.md)
+17. [Glossário e referência](15-glossary-and-reference.md)
 
 ## Mapa rápido
 
@@ -31,6 +32,7 @@
 | Lista de bolhas / `members.json` | [07-public-members-directory.md](07-public-members-directory.md) |
 | Pedidos SSH `entre` | [09-terminal-entre.md](09-terminal-entre.md) |
 | Criar conta membro | [10-user-provisioning-and-admin-ops.md](10-user-provisioning-and-admin-ops.md) |
+| Reparar home incompleta / `Index of /~USER` | [16-repair-users.md](16-repair-users.md) |
 | Email Mailgun / legado | [08-email.md](08-email.md) |
 
 ## Diagramas (Mermaid)
diff --git a/docs/admin.md b/docs/admin.md
@@ -563,6 +563,8 @@ sudo python3 REPO/scripts/admin/repair_user.py --all-users --dry-run --verbose
 sudo python3 REPO/scripts/admin/repair_user.py --all-users
 ```
 
+Procedimento completo: [docs/16-repair-users.md](16-repair-users.md).
+
 ### Corrigir IRC de todos os usuários
 
 ```bash