community.general.logrotate module – Manage logrotate configurations

Note

This module is part of the community.general collection (version 12.5.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.general.logrotate.

New in community.general 12.5.0

Synopsis

• Manage logrotate configuration files and settings.

• Create, update, or remove logrotate configurations for applications and services.

Requirements

The below requirements are needed on the host that executes this module.

• logrotate >= 3.8.0

Parameters

Parameter	Comments
compress boolean	Compress rotated log files. Choices: false true
compress_options string	Options to pass to compression program. For compression_method=gzip, use -9 for best compression, -1 for fastest. For compression_method=xz, use -9 for best compression.
compression_method string	Compression method to use. Requires logrotate 3.18.0 or later for xz and zstd. Choices: "gzip" "bzip2" "xz" "zstd" "lzma" "lz4"
config_dir path	Directory where logrotate configurations are stored. Default is /etc/logrotate.d for system-wide configurations. Use ~/.logrotate.d for user-specific configurations. This directory must exist before using the module.
copy boolean	Copy the log file but do not truncate the original. Takes precedence over rename_copy and copy_truncate. Choices: false true
copy_truncate boolean	Copy the log file and then truncate it in place. Useful for applications that cannot be told to close their logfile. Choices: false true
create string	Create new log file with specified permissions after rotation. Format is mode owner group (for example 0640 root adm). Set to null or omit to use nocreate.
create_old_dir boolean	Create old_dir directory if it does not exist. Choices: false true
date_ext boolean	Use date as extension for rotated files (using the date format specified in date_format instead of sequential numbers). Choices: false true
date_format string	Format for date extension. Use with date_ext=true. Format specifiers are %Y year, %m month, %d day, %s seconds since epoch.
date_yesterday boolean	Use yesterday’s date for date_ext instead of today’s date. Useful for rotating logs that span midnight. Choices: false true
delay_compress boolean	Postpone compression of the previous log file to the next rotation cycle. Useful for applications that keep writing to the old log file for some time. Choices: false true
enabled boolean	Whether the configuration should be enabled. When false, adds .disabled extension to the config file. Choices: false true
extension string	Extension to use for rotated log files (including dot). Useful when compress=false.
first_action list / elements=string	Commands to execute once before all log files that match the wildcard pattern are rotated.
include path	Include additional configuration files from specified directory.
last_action list / elements=string	Commands to execute once after all log files that match the wildcard pattern are rotated.
mail string	Mail logs to specified address when removed. Set to null or omit to not mail logs.
mail_first boolean	Mail just-created log file, not the about-to-expire one. Choices: false true
mail_last boolean	Mail about-to-expire log file (default). Choices: false true
max_age integer	Remove rotated logs older than specified number of days.
max_size string	Rotate log file when it grows bigger than specified size, but at most once per rotation_period. Format is number[k|M|G] (for example 100M, 1G).
min_size string	Rotate log file only if it has grown bigger than specified size. Format is number[k|M|G] (for example 100M, 1G). Used with time-based rotation to avoid rotating too small files.
missing_ok boolean	Do not issue an error if the log file is missing. Choices: false true
name aliases: config_name string / required	Name of the logrotate configuration. This creates a file in config_dir with this name.
no_delay_compress boolean	Opposite of delay_compress. Ensure compression happens immediately. Note that in logrotate, no_delay_compress is the default behavior. Choices: false true
no_old_dir boolean	Keep rotated logs in the same directory as the original log. Choices: false true
not_if_empty boolean	Do not rotate the log file if it is empty. Set to false to rotate even empty log files (equivalent to ifempty in logrotate). Choices: false true
old_dir path	Move rotated logs into specified directory.
paths list / elements=path	List of log file paths or patterns to rotate. Can include wildcards (for example /var/log/app/*.log). Required when creating a new configuration (state=present and config file does not exist). Optional when modifying existing configuration (for example to enable/disable).
post_rotate list / elements=string	Commands to execute after rotating the log file. Can be a single string or list of commands.
pre_remove list / elements=string	Commands to execute before removing rotated log files.
pre_rotate list / elements=string	Commands to execute before rotating the log file. Can be a single string or list of commands.
rename_copy boolean	Rename and copy the log file, leaving the original in place. Choices: false true
rotate_count integer	Number of rotated log files to keep. Set to 0 to disable rotation (keep only current log). Set to -1 to keep all rotated logs (not recommended).
rotation_period string	How often to rotate the logs. If not specified when modifying an existing configuration, the existing value is preserved. When creating a new configuration, this option is only included if specified. Choices: "daily" "weekly" "monthly" "yearly"
shared_scripts boolean	Run pre_rotate and post_rotate scripts only once for all matching log files. Choices: false true
shred boolean	Use shred to securely delete rotated log files. Uses shred -u to overwrite files before deleting. Choices: false true
shred_cycles integer	Number of times to overwrite files when using shred=true.
size string	Rotate log file when it grows bigger than specified size. Format is number[k|M|G] (for example 100M, 1G). Overrides rotation_period when set. If not specified, existing value be preserved when modifying configuration. When creating new configuration, this option be omitted if not specified.
start integer	Base number for rotated files. Allowed values are from 0 to 999. For example, 1 gives files .1, .2, and so on instead of .0, .1.
state string	Whether the configuration should be present or absent. Choices: "present" "absent"
su string	Set user and group for rotated files. Format is user group (for example, www-data adm). Set to "" (empty string) to remove the directive from existing configurations. Set to null or omit to leave the existing value unchanged (when modifying) or not set (when creating).
syslog boolean	Send logrotate messages to syslog. Choices: false true
taboo_ext list / elements=string	List of extensions that logrotate should not touch. Set to null or empty list to clear defaults.

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target.
diff_mode	Support: full	Returns details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

- name: Ensure logrotate config directory exists
  ansible.builtin.file:
    path: /etc/logrotate.d
    state: directory
    mode: '0755'

- name: Configure log rotation for Nginx
  community.general.logrotate:
    name: nginx
    paths:
      - /var/log/nginx/*.log
    rotation_period: daily
    rotate_count: 14
    compress: true
    compress_options: "-9"
    delay_compress: true
    missing_ok: true
    not_if_empty: true
    create: "0640 www-data adm"
    shared_scripts: true
    post_rotate:
      - "[ -f /var/run/nginx.pid ] && kill -USR1 $(cat /var/run/nginx.pid)"
      - "echo 'Nginx logs rotated'"

- name: Configure size-based rotation for application logs
  community.general.logrotate:
    name: myapp
    paths:
      - /var/log/myapp/app.log
      - /var/log/myapp/debug.log
    size: 100M
    rotate_count: 10
    compress: true
    compress_options: "-1"
    date_ext: true
    date_yesterday: true
    date_format: -%Y%m%d.%s
    missing_ok: true
    copy_truncate: true

- name: Configure log rotation with secure deletion
  community.general.logrotate:
    name: secure-app
    paths:
      - /var/log/secure-app/*.log
    rotation_period: weekly
    rotate_count: 4
    shred: true
    shred_cycles: 3
    compress: true
    compress_options: "-9"

- name: Configure log rotation with custom start number
  community.general.logrotate:
    name: custom-start
    paths:
      - /var/log/custom/*.log
    rotation_period: monthly
    rotate_count: 6
    start: 1
    compress: true

- name: Configure log rotation with old directory
  community.general.logrotate:
    name: with-old-dir
    paths:
      - /opt/app/logs/*.log
    rotation_period: weekly
    rotate_count: 4
    old_dir: /var/log/archives
    create_old_dir: true
    compress: true
    compression_method: zstd

- name: Disable logrotate configuration
  community.general.logrotate:
    name: old-service
    enabled: false

- name: Remove logrotate configuration
  community.general.logrotate:
    name: deprecated-app
    state: absent

- name: Complex configuration with multiple scripts
  community.general.logrotate:
    name: complex-app
    paths:
      - /var/log/complex/*.log
    rotation_period: monthly
    rotate_count: 6
    compress: true
    delay_compress: false
    pre_rotate:
      - "echo 'Starting rotation for complex app'"
      - "systemctl stop complex-app"
    post_rotate:
      - "systemctl start complex-app"
      - "echo 'Rotation completed'"
      - "logger -t logrotate 'Complex app logs rotated'"
    first_action:
      - "echo 'First action: Starting batch rotation'"
    last_action:
      - "echo 'Last action: Batch rotation complete'"

- name: User-specific logrotate configuration
  community.general.logrotate:
    name: myuser-apps
    config_dir: ~/.logrotate.d
    paths:
      - ~/app/*.log
      - ~/.cache/*/*.log
    rotation_period: daily
    rotate_count: 30
    compress: true
    su: "{{ ansible_user_id }} users"

- name: Configuration with copy instead of move
  community.general.logrotate:
    name: copy-config
    paths:
      - /var/log/copy-app/*.log
    rotation_period: daily
    rotate_count: 7
    copy: true

- name: Configuration with syslog notifications
  community.general.logrotate:
    name: syslog-config
    paths:
      - /var/log/syslog-app/*.log
    rotation_period: daily
    rotate_count: 14
    syslog: true
    compress: true

- name: Configuration without compression
  community.general.logrotate:
    name: nocompress-config
    paths:
      - /var/log/nocompress/*.log
    rotation_period: daily
    rotate_count: 7
    compress: false

- name: Configuration with custom taboo extensions
  community.general.logrotate:
    name: taboo-config
    paths:
      - /var/log/taboo/*.log
    rotation_period: daily
    rotate_count: 7
    taboo_ext: [".backup", ".tmp", ".temp"]

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
backup_file string	Path to the backup of the original configuration file, if it was backed up. Returned: success when backup was made Sample: "/etc/logrotate.d/nginx.20250101_120000"
config_content string	The generated logrotate configuration content. Returned: success when state=present Sample: "/var/log/nginx/*.log {\n    daily\n    rotate 14\n    compress\n    compress_options -9\n    delay_compress\n    missing_ok\n    notifempty\n    create 0640 www-data adm\n    shared_scripts\n    post_rotate\n        [ -f /var/run/nginx.pid ] && kill -USR1 $(cat /var/run/nginx.pid)\n        echo 'Nginx logs rotated'\n    endscript\n}\n"
config_file string	Path to the created/updated logrotate configuration file. Returned: success when state=present Sample: "/etc/logrotate.d/nginx"
enabled_state boolean	Current enabled state of the configuration. Returned: success Sample: true

Authors

• Aleksandr Gabidullin (@a-gabidullin)

Collection links

• Issue Tracker
• Repository (Sources)
• Ask for help
• Submit a bug report
• Request a feature
• Communication