WARNING: Version 5.5 of Beats has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
Upgrading from 1.x to 5.x
editUpgrading from 1.x to 5.x
editBefore upgrading your Beats, please review the breaking changes doc.
In addition to the subsections here, please read Upgrading the Elasticsearch Mapping Template.
Migrating Configuration Files
editBeats 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 Registry File Location and Format
editFilebeat 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
.
Upgrading Topbeat to Metricbeat
editWhen upgrading to Metricbeat, keep in mind that any data you’ve collected with Topbeat is not compatible with the 5.0 version of the Beats dashboards because the underlying event data structures have changed.
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.