Upgrading from 1.x to 5.x

Beats 5.0 comes with several backwards incompatible configuration changes. However, we provide a script that can automatically fixup the most common settings in your configuration files.

You can find this script in the Beats download packages. For the .tar.gz and .zip archives, look under:

./scripts/migrate_beat_config_1_x_to_5_0.py

For the .deb and .rpm packages, look under the /usr/share/<beatname>/scripts/ folder, for example:

/usr/share/packetbeat/scripts/migrate_beat_config_1_x_to_5_0.py

Python 2.7 or later is required for executing the migration script.

To upgrade your configuration file automatically, simply pass it as an argument to the migration script, for example:

> ./scripts/migrate_beat_config_1_x_to_5_0.py packetbeat.yml
Backup file created: packetbeat.yml.bak

The script will automatically create a backup file and overwrite the input file with the upgraded version. You can also use the --dry option, which doesn’t modify the input file, but outputs the upgraded version to stdout instead.

Filebeat stores the read offset in a registry file that it persists to disk. The format of this file has changed in version 5.0, but Filebeat automatically upgrades the format on the first run, so there’s normally no action required on upgrading.

If you have installed Filebeat from the DEB or RPM packages, the location of the file stays the same as well (/var/lib/filebeat/registry). Also if you’ve installed Filebeat as a service on Windows, the location stays the same (C:\ProgramData\filebeat\registry).

If you are running Filebeat from the tar.gz archive, however, the location of the registry file has changed. In version 1.x it was by default named .filebeat in the current working directory. In version 5.0, it is data/registry relative to the binary location. For upgrading in this case, we recommend copying the .filebeat file to data/registry.

With the Beats 5.0 release, Topbeat is replaced by Metricbeat, which offers more functionality. More precisely, the Topbeat functionality is roughly equivalent to the "system" module in Metricbeat.

While there is no automatic way to convert a Topbeat configuration file to the equivalent of a Metricbeat configuration file, both configurations are simple enough that migrating shouldn’t take long.

For example, this is the input section of the Topbeat configuration file:

input:
  # In seconds, defines how often to read server statistics
  period: 10

  # Regular expression to match the processes that are monitored
  # By default, all the processes are monitored
  procs: [".*"]

  # Statistics to collect (all enabled by default)
  stats:
    # per system statistics, by default is true
    system: true

    # per process statistics, by default is true
    process: true

    # file system information, by default is true
    filesystem: true

    # cpu usage per core, by default is false
    cpu_per_core: false

And here is the equivalent configuration for the system module in Metricbeat:

metricbeat.modules:

#------------------------------- System Module -------------------------------
- module: system
  metricsets:
    # CPU stats
    - cpu

    # System Load stats
    - load

    # Per filesystem stats
    - filesystem

    # Memory stats
    - memory

    # Network stats
    - network

    # Per process stats
    - process
  enabled: true
  period: 10s
  processes: ['.*']

The remaining configuration options (outputs, name, tags) stay the same or can be upgraded using the migration script.