Como impedir execuções simultâneas de um script administrativo: flock, lockf e mutex nomeado no Windows

Objetivo

Garantir que apenas uma instância de um script administrativo seja executada de cada vez e que uma execução anterior que tenha abortado não bloqueie permanentemente as seguintes.

Pré-requisitos

flock (util-linux) no Linux; lockf no FreeBSD; PowerShell 5.1 ou 7.x no Windows.

Passos

1. No Linux, encapsule o comando com flock -n -E 75 /var/lock/my-admin-script.lock /usr/local/bin/my-admin-script.sh (sem -E, um conflito de lock e uma falha do script retornam ambos 1 e não se distinguem), ou obtenha o lock dentro do próprio script, usando um descritor de arquivo: exec 9>/var/lock/my-admin-script.lock; flock -n 9 || { echo "already running"; exit 75; }. O flock(1), descrito na documentação como um utilitário para "manage locks from shell scripts" (gerenciar locks a partir de shell scripts), associa o lock a um descritor de arquivo aberto. Por isso o lock é liberado automaticamente quando o último processo que mantém esse descritor termina ou é morto; ao contrário de um arquivo PID deixado para trás, ele não fica obsoleto. Os processos filhos herdam o descritor: um daemon iniciado a partir do script com lock mantém o lock até terminar, a menos que seja iniciado com 9>&-.
2. Use -n/--nonblocking para falhar imediatamente se outra instância já mantiver o lock (adequado para uma tarefa agendada que deve ignorar uma execução sobreposta), ou -w <seconds> para esperar até um tempo limite.
3. No FreeBSD, o equivalente é lockf -k -t 0 /var/run/my-admin-script.lock /usr/local/bin/my-admin-script.sh. O lockf(1) é descrito na documentação como um utilitário que "acquires an exclusive lock" (obtém um lock exclusivo) sobre um arquivo, criando-o se necessário, executa o comando indicado enquanto o mantém e libera o lock quando o comando termina. Sem -k, ele apaga o arquivo de lock ao sair; um conflito de lock termina com o código 75 (EX_TEMPFAIL).
4. No Windows, use um mutex nomeado, válido em todo o sistema, em vez de um arquivo de lock: $mutex = New-Object System.Threading.Mutex($false, "Global\MyAdminScript"); try { $got = $mutex.WaitOne(0) } catch [System.Threading.AbandonedMutexException] { $got = $true }; if (-not $got) { Write-Error "already running"; exit 75 }; try { <script body> } finally { $mutex.ReleaseMutex(); $mutex.Dispose() }. Se o detentor anterior morreu, o WaitOne seguinte lança AbandonedMutexException, mas concede a posse; daí o catch. A documentação do .NET distingue os mutexes sem nome, locais ao processo, dos "named system mutexes" (mutexes de sistema nomeados), visíveis entre processos; o prefixo Global\ faz o nome abranger todas as sessões de usuário.
5. Libere sempre o lock/mutex num bloco finally/trap, para que uma exceção durante o corpo do script também o libere; não dependa apenas do caminho normal de saída.
6. Registre nos logs os dois resultados de forma distinta: "skipped, another instance is running" (ignorado, outra instância está em execução) não é o mesmo evento que "started" (iniciado) e não deve ser tratado como falha por qualquer sistema que monitore o agendamento.

Resultado esperado

Iniciar o script uma segunda vez enquanto o primeiro ainda está em execução faz com que a segunda instância termine imediatamente (ou espere, conforme o modo escolhido), em vez de executar as duas cópias sobre o mesmo estado; matar o processo da primeira execução libera o lock sem necessidade de limpeza manual.

Limites e base de verificação

O lock consultivo do flock só impede outros processos que também passem por flock/flock(2); não impede um processo que ignore o lock e edite diretamente os mesmos arquivos. Arquivos de lock num sistema de arquivos de rede (NFS) podem não aplicar a semântica do flock de forma consistente entre hosts; mantenha o arquivo de lock em armazenamento local para ter garantia num único host. Um mutex nomeado criado por uma conta pode ficar inacessível (acesso negado) para um script executado sob outra conta; execute todas as instâncias sob a mesma conta ou conceda o acesso explicitamente.