O cron é o agendador de tarefas clássico dos sistemas Unix e Linux: você descreve quando um comando deve rodar usando uma expressão curta, e o sistema cuida do resto. A sintaxe é compacta e cheia de detalhes que só aparecem na primeira vez que um job roda no horário errado. Este guia ensina a ler e escrever expressões cron e lista as pegadinhas mais comuns.
Os cinco campos
Uma expressão cron padrão tem cinco campos separados por espaço:
┌───────── minuto (0–59)
│ ┌─────── hora (0–23)
│ │ ┌───── dia do mês (1–31)
│ │ │ ┌─── mês (1–12 ou JAN–DEC)
│ │ │ │ ┌─ dia da semana (0–7 ou SUN–SAT; 0 e 7 são domingo)
│ │ │ │ │
* * * * * comando a executarA tarefa dispara quando o horário atual satisfaz todos os campos. Um asterisco significa "qualquer valor".
Caracteres especiais
*: qualquer valor daquele campo.,: lista de valores.1,15no dia do mês significa dias 1 e 15.-: intervalo.1-5no dia da semana significa de segunda a sexta./: passo.*/15no minuto significa a cada 15 minutos (0, 15, 30, 45).
Exemplos comuns
*/5 * * * * a cada 5 minutos
0 * * * * no início de cada hora
0 9 * * 1-5 às 9h00, de segunda a sexta
30 2 1 * * às 2h30 do dia 1 de cada mês
0 0 * * 0 à meia-noite de todo domingo
15 14 1,15 * * às 14h15 nos dias 1 e 15
0 8-18/2 * * * a cada 2 horas, das 8h às 18h (8, 10, 12, 14, 16, 18)Se quiser conferir o que uma expressão faz, cole-a no tradutor de expressão cron, que descreve o agendamento em português.
Atalhos
Muitas implementações aceitam apelidos como @hourly,
@daily, @weekly, @monthly,
@yearly e @reboot (na inicialização). Eles são
extensões e não estão presentes em todos os agendadores, então confira a
documentação do seu ambiente antes de depender deles.
Pegadinhas que causam bugs reais
1. Dia do mês e dia da semana juntos funcionam como "OU"
Quando os dois campos são restritos (nenhum é
*), a maioria dos crons executa a tarefa se qualquer um
dos dois combinar. Assim, 0 0 13 * 5 não roda "só na
sexta-feira 13": roda em todo dia 13 e em toda
sexta-feira. Para obter o efeito de "E", é preciso filtrar dentro do
próprio comando.
2. O passo não é contínuo
A expressão */7 * * * * dispara nos minutos 0, 7, 14, 21, 28,
35, 42, 49 e 56 e depois reinicia em 0 na hora seguinte. O
intervalo entre 56 e 0 é de apenas 4 minutos, não 7. Passos só dividem
de forma uniforme quando o valor divide o tamanho do campo (5, 10, 15, 20,
30 para minutos).
3. Fuso horário e horário de verão
O cron usa o fuso do sistema. Em locais com horário de verão, um job marcado para um horário que "não existe" na virada (por exemplo, 2h30 quando o relógio pula de 2h para 3h) pode não rodar, e um marcado para um horário que se repete pode rodar duas vezes. Servidores configurados em UTC evitam o problema, e o conversor de fuso horário ajuda a converter o horário desejado.
4. O caractere % é especial no crontab
Dentro de uma linha de crontab, o sinal % é interpretado
como quebra de linha. Um comando como
date +%Y-%m-%d precisa ter cada % escapado com
barra invertida (\%) ou ser movido para um script.
5. Ambiente mínimo
O cron executa comandos com um ambiente reduzido: PATH
curto, sem as variáveis do seu shell de login. Um comando que funciona
no terminal pode falhar no cron por não encontrar o executável. Use
caminhos completos e defina as variáveis necessárias no script.
6. Execuções que se sobrepõem
Se uma tarefa demorar mais que o intervalo entre execuções, duas
instâncias podem rodar ao mesmo tempo. Proteja jobs longos com um
bloqueio, como o utilitário flock.
Variações de outras plataformas
Nem toda "expressão cron" é igual à do crontab tradicional. Bibliotecas
como Quartz e Spring costumam usar seis ou sete campos,
acrescentando segundos (e, às vezes, ano) e adotando caracteres como
?. Serviços de nuvem têm suas próprias variações. Antes de
copiar uma expressão de um lugar para outro, confirme quantos campos e
quais símbolos a ferramenta de destino aceita. Se o agendamento
depender de comparar datas em segundos, o guia
Timestamp Unix e o problema do ano 2038
também pode ser útil.