linux_cron_d

Rola Ansible do zarządzania systemowymi wpisami cron w katalogu /etc/cron.d.

Rola zakłada składnię właściwą dla /etc/cron.d, czyli wpis zawiera również użytkownika, np.:

* * * * * root id

Dla zwykłego crontaba użytkownika wpis wyglądałby inaczej, bez pola użytkownika:

* * * * * id

Funkcje

• tworzenie osobnego pliku w /etc/cron.d dla każdego wpisu,
• usuwanie wpisów przez state: absent,
• domyślny state: present,
• wymagana obecność pól name i content,
• możliwość przekazania głównej listy i dodatkowej listy wpisów,
• tryb wymuszonego włączenia crona,
• tryb wymuszonego wyłączenia crona przez zakomentowanie,
• tryb zachowania obecnego stanu włączenia/wyłączenia przy aktualizacji treści,
• walidacja zmiennych przez meta/argument_specs.yml.

Wymagania

• Ansible 2.14 lub nowszy.
• Dostęp z uprawnieniami pozwalającymi zapisywać do /etc/cron.d, zwykle become: true.

Zmienne

linux_cron_d_entries

Główna lista wpisów cron.d zarządzanych przez rolę.

Domyślnie:

linux_cron_d_entries: []

Format:

linux_cron_d_entries:
  - name: test-id
    content: "* * * * * root id"
    state: present

Pola:

Pole	Wymagane	Domyślnie	Opis
name	tak	brak	Nazwa logiczna wpisu. Na jej podstawie powstaje nazwa pliku w /etc/cron.d.
content	tak	brak	Pełna linia cron.d, np. * * * * * root id.
state	nie	present	present albo absent.

linux_cron_d_extra_entries

Dodatkowa lista wpisów, która zostanie połączona z linux_cron_d_entries.

Przydaje się, gdy masz np. wspólne crony zdefiniowane globalnie i chcesz dołożyć wpisy specyficzne dla hosta albo grupy.

Domyślnie:

linux_cron_d_extra_entries: []

linux_cron_d_state_mode

Steruje tym, czy wpisy z state: present mają być aktywne, wyłączone, czy mają zachować swój obecny stan.

Domyślnie:

linux_cron_d_state_mode: enabled

Dostępne wartości:

Wartość	Zachowanie
enabled	Utworzy lub zaktualizuje wpis i upewni się, że nie jest zakomentowany.
disabled	Utworzy lub zaktualizuje wpis, ale zapisze go jako zakomentowany.
preserve	Zaktualizuje treść, ale zachowa obecny stan: jeśli był zakomentowany, pozostanie zakomentowany; jeśli był aktywny, pozostanie aktywny.

Priorytet ma state wpisu. Jeżeli wpis ma state: absent, plik zostanie usunięty niezależnie od wartości linux_cron_d_state_mode.

Pozostałe zmienne

linux_cron_d_dir: /etc/cron.d
cron_name_prefix: ""
cron_name_suffix: ""
linux_cron_d_owner: root
linux_cron_d_group: root
linux_cron_d_file_mode: "0644"

Przykłady użycia

1. Prosty aktywny cron

- name: Manage cron.d entries
  hosts: all
  become: true
  roles:
    - role: linux_cron_d
      vars:
        linux_cron_d_entries:
          - name: test-id
            content: "* * * * * root id"

Wynik w /etc/cron.d/test-id:

# Ansible managed
# Name: test-id

* * * * * root id

2. Wymuszenie wyłączenia crona przez zakomentowanie

- name: Disable cron.d entry
  hosts: all
  become: true
  roles:
    - role: linux_cron_d
      vars:
        linux_cron_d_state_mode: disabled
        linux_cron_d_entries:
          - name: test-id
            content: "* * * * * root id"

Wynik:

# Ansible managed
# Name: test-id

# * * * * * root id

3. Aktualizacja treści z zachowaniem stanu włączenia

- name: Update cron.d entry and preserve current enabled/disabled state
  hosts: all
  become: true
  roles:
    - role: linux_cron_d
      vars:
        linux_cron_d_state_mode: preserve
        linux_cron_d_entries:
          - name: test-id
            content: "*/5 * * * * root /usr/bin/id"

Jeżeli istniejący wpis był aktywny, po aktualizacji pozostanie aktywny:

*/5 * * * * root /usr/bin/id

Jeżeli istniejący wpis był zakomentowany, po aktualizacji pozostanie zakomentowany:

# */5 * * * * root /usr/bin/id

Jeżeli plik nie istniał, tryb preserve utworzy go jako aktywny. Nie ma wtedy wcześniejszego stanu, który można zachować.

4. Wymuszenie włączenia crona

- name: Enable cron.d entry
  hosts: all
  become: true
  roles:
    - role: linux_cron_d
      vars:
        linux_cron_d_state_mode: enabled
        linux_cron_d_entries:
          - name: test-id
            content: "*/5 * * * * root /usr/bin/id"

Jeżeli wpis był wcześniej zakomentowany, zostanie odkomentowany.

5. Usunięcie crona

- name: Remove cron.d entry
  hosts: all
  become: true
  roles:
    - role: linux_cron_d
      vars:
        linux_cron_d_entries:
          - name: test-id
            content: "* * * * * root id"
            state: absent

Efekt:

/etc/cron.d/test-id zostanie usunięty

content jest nadal wymagany ze względu na spójność struktury danych i walidację roli.

6. Główna lista plus dodatkowa lista

common_crons:
  - name: cleanup-tmp
    content: "15 3 * * * root /usr/local/sbin/cleanup-tmp"

linux_cron_d_entries:
  - name: test-id
    content: "* * * * * root id"

linux_cron_d_extra_entries: "{{ common_crons }}"

Rola zarządzi finalnie obiema listami.

7. Przykład z group_vars

group_vars/all/cron.yml:

common_crons:
  - name: cleanup-tmp
    content: "15 3 * * * root /usr/local/sbin/cleanup-tmp"

linux_cron_d_extra_entries: "{{ common_crons }}"

host_vars/server1.yml:

linux_cron_d_entries:
  - name: server1-backup-check
    content: "*/30 * * * * root /usr/local/sbin/backup-check"

Playbook:

- name: Manage system cron.d entries
  hosts: linux
  become: true
  roles:
    - role: linux_cron_d

Zasady działania

Nazwa pliku

Pole name jest zamieniane na bezpieczną nazwę pliku. Znaki inne niż litery, cyfry, _, . i - są zamieniane na _. Opcjonalne cron_name_prefix i cron_name_suffix są dodawane odpowiednio przed i po name przed wygenerowaniem nazwy pliku.

Przykład:

cron_name_prefix: "prod-"
cron_name_suffix: ".cron"
name: "backup check / server1"

utworzy plik:

/etc/cron.d/prod-backup_check___server1.cron

Priorytet state: absent

Jeśli wpis ma state: absent, plik zostanie usunięty i rola nie będzie wykonywać logiki enabled, disabled ani preserve dla tego wpisu.

Przykład:

linux_cron_d_state_mode: preserve

linux_cron_d_entries:
  - name: test-id
    content: "* * * * * root id"
    state: absent

Wynik:

/etc/cron.d/test-id zostanie usunięty

Tryb preserve

Tryb preserve sprawdza istniejący plik. Jeżeli znajdzie zakomentowaną linię crona, traktuje wpis jako wyłączony i po aktualizacji nadal zapisze go jako zakomentowany.

Komentarze techniczne generowane przez rolę, takie jak # Ansible managed i # Name: ..., nie są traktowane jako wyłączony cron.

Ograniczenia

• Rola zarządza jednym wpisem cron w jednym pliku.
• Rola jest przeznaczona do /etc/cron.d, a nie do osobistych crontabów użytkowników.
• Rola nie waliduje składni samego wyrażenia cron. Sprawdza tylko obecność wymaganych pól i dozwolone wartości state.

Instalacja w projekcie

Przykładowo:

project/
├── playbook.yml
└── roles/
    └── linux_cron_d/

Skopiuj katalog linux_cron_d do roles/ i użyj roli w playbooku.

---

English documentation

Overview

linux_cron_d is an Ansible role for managing system cron entries stored in /etc/cron.d.

The role is designed for the /etc/cron.d syntax, where the cron line includes the user field, for example:

* * * * * root id

A regular user crontab uses a different syntax and does not include the user field:

* * * * * id

Features

• creates one separate file in /etc/cron.d for each managed entry,
• removes entries with state: absent,
• uses state: present by default,
• requires both name and content,
• supports a main list and an additional list of entries,
• can force a cron entry to be enabled,
• can force a cron entry to be disabled by commenting it out,
• can update the cron command while preserving the current enabled or disabled state,
• validates variables through meta/argument_specs.yml.

Requirements

• Ansible 2.14 or newer.
• Permissions to write to /etc/cron.d, usually by using become: true.

Variables

linux_cron_d_entries

Main list of cron.d entries managed by this role.

Default:

linux_cron_d_entries: []

Example:

linux_cron_d_entries:
  - name: test-id
    content: "* * * * * root id"
    state: present

Fields:

Field	Required	Default	Description
name	yes	none	Logical entry name. It is used to generate the filename under /etc/cron.d.
content	yes	none	Full cron.d line, for example * * * * * root id.
state	no	present	Either present or absent.

linux_cron_d_extra_entries

Additional list of entries merged with linux_cron_d_entries.

This is useful when you have common cron jobs defined globally and want to add host-specific or group-specific jobs separately.

Default:

linux_cron_d_extra_entries: []

linux_cron_d_state_mode

Controls whether entries with state: present should be enabled, disabled, or keep their current state.

Default:

linux_cron_d_state_mode: enabled

Available values:

Value	Behaviour
enabled	Creates or updates the entry and ensures it is not commented out.
disabled	Creates or updates the entry but writes it as a commented cron line.
preserve	Updates the content but keeps the current state. If it was commented out, it remains commented out. If it was active, it remains active.

The per-entry state has priority. If an entry has state: absent, the file is removed regardless of linux_cron_d_state_mode.

Other variables

linux_cron_d_dir: /etc/cron.d
cron_name_prefix: ""
cron_name_suffix: ""
linux_cron_d_owner: root
linux_cron_d_group: root
linux_cron_d_file_mode: "0644"

Usage examples

1. Simple active cron entry

- name: Manage cron.d entries
  hosts: all
  become: true
  roles:
    - role: linux_cron_d
      vars:
        linux_cron_d_entries:
          - name: test-id
            content: "* * * * * root id"

Result in /etc/cron.d/test-id:

# Ansible managed
# Name: test-id

* * * * * root id

2. Force a cron entry to be disabled by commenting it out

- name: Disable cron.d entry
  hosts: all
  become: true
  roles:
    - role: linux_cron_d
      vars:
        linux_cron_d_state_mode: disabled
        linux_cron_d_entries:
          - name: test-id
            content: "* * * * * root id"

Result:

# Ansible managed
# Name: test-id

# * * * * * root id

3. Update the command while preserving the enabled or disabled state

- name: Update cron.d entry and preserve current enabled/disabled state
  hosts: all
  become: true
  roles:
    - role: linux_cron_d
      vars:
        linux_cron_d_state_mode: preserve
        linux_cron_d_entries:
          - name: test-id
            content: "*/5 * * * * root /usr/bin/id"

If the existing entry was active, it remains active after the update:

*/5 * * * * root /usr/bin/id

If the existing entry was commented out, it remains commented out after the update:

# */5 * * * * root /usr/bin/id

If the file does not exist yet, preserve creates it as active because there is no previous state to preserve.

4. Force a cron entry to be enabled

- name: Enable cron.d entry
  hosts: all
  become: true
  roles:
    - role: linux_cron_d
      vars:
        linux_cron_d_state_mode: enabled
        linux_cron_d_entries:
          - name: test-id
            content: "*/5 * * * * root /usr/bin/id"

If the entry was previously commented out, it will be uncommented.

5. Remove a cron entry

- name: Remove cron.d entry
  hosts: all
  become: true
  roles:
    - role: linux_cron_d
      vars:
        linux_cron_d_entries:
          - name: test-id
            content: "* * * * * root id"
            state: absent

Result:

/etc/cron.d/test-id is removed

content is still required to keep a consistent data structure and role validation.

6. Main list plus additional list

common_crons:
  - name: cleanup-tmp
    content: "15 3 * * * root /usr/local/sbin/cleanup-tmp"

linux_cron_d_entries:
  - name: test-id
    content: "* * * * * root id"

linux_cron_d_extra_entries: "{{ common_crons }}"

The role manages entries from both lists.

7. Example with group_vars and host_vars

group_vars/all/cron.yml:

common_crons:
  - name: cleanup-tmp
    content: "15 3 * * * root /usr/local/sbin/cleanup-tmp"

linux_cron_d_extra_entries: "{{ common_crons }}"

host_vars/server1.yml:

linux_cron_d_entries:
  - name: server1-backup-check
    content: "*/30 * * * * root /usr/local/sbin/backup-check"

Playbook:

- name: Manage system cron.d entries
  hosts: linux
  become: true
  roles:
    - role: linux_cron_d

Behaviour details

Filename generation

The name field is converted into a safe filename. Characters other than letters, digits, _, ., and - are replaced with _. Optional cron_name_prefix and cron_name_suffix are added before and after name before the filename is generated.

Example:

cron_name_prefix: "prod-"
cron_name_suffix: ".cron"
name: "backup check / server1"

creates:

/etc/cron.d/prod-backup_check___server1.cron

Priority of state: absent

If an entry has state: absent, the file is removed and the role does not apply the enabled, disabled, or preserve logic to that entry.

Example:

linux_cron_d_state_mode: preserve

linux_cron_d_entries:
  - name: test-id
    content: "* * * * * root id"
    state: absent

Result:

/etc/cron.d/test-id is removed

preserve mode

The preserve mode checks the existing file. If it finds a commented cron line, it treats the entry as disabled and writes the updated content as commented out.

Technical comments generated by the role, such as # Ansible managed and # Name: ..., are not treated as disabled cron entries.

Limitations

• The role manages one cron entry per file.
• The role is intended for /etc/cron.d, not user crontabs.
• The role does not validate the cron expression syntax. It only checks required fields and allowed state values.

Installation in a project

Example layout:

project/
├── playbook.yml
└── roles/
    └── linux_cron_d/

Copy the linux_cron_d directory into roles/ and use the role in your playbook.