diff --git a/filebeat/_meta/common.reference.p2.yml b/filebeat/_meta/common.reference.p2.yml
index 2296ea1235a8..c7bb472a147b 100644
--- a/filebeat/_meta/common.reference.p2.yml
+++ b/filebeat/_meta/common.reference.p2.yml
@@ -32,6 +32,14 @@
 # batch of events has been published successfully. The default value is 0s.
 #filebeat.registry.flush: 0s
 
+
+# Starting with Filebeat 7.0, the registry uses a new directory format to store
+# Filebeat state. After you upgrade, Filebeat will automatically migrate a 6.x
+# registry file to use the new directory format. If you changed
+# filebeat.registry.path while upgrading, set filebeat.registry.migrate_file to
+# point to the old registry file.
+#filebeat.registry.migrate_file: ${path.data}/registry
+
 # By default Ingest pipelines are not updated if a pipeline with the same ID
 # already exists. If this option is enabled Filebeat overwrites pipelines
 # everytime a new Elasticsearch connection is established.
diff --git a/filebeat/docs/filebeat-general-options.asciidoc b/filebeat/docs/filebeat-general-options.asciidoc
index bd846145ebea..b78e4545ec15 100644
--- a/filebeat/docs/filebeat-general-options.asciidoc
+++ b/filebeat/docs/filebeat-general-options.asciidoc
@@ -73,6 +73,24 @@ NOTE: Filtering out a huge number of logs can cause many registry updates, slowi
 down processing. Setting `registry.flush` to a value >0s reduces write operations,
 helping Filebeat process more events.
 
+[float]
+==== `registry.migrate_file`
+
+Prior to Filebeat 7.0 the registry is stored in a single file. When you upgrade
+to 7.0, Filebeat will automatically migrate the old Filebeat 6.x registry file
+to use the new directory format. Filebeat looks for the file in the location
+specified by `filebeat.registry.path`. If you changed the path while upgrading,
+set `filebeat.registry.migrate_file` to point to the old registry file.
+
+[source,yaml]
+-------------------------------------------------------------------------------------
+filebeat.registry.path: ${path.data}/registry
+filebeat.registry.migrate_file: /path/to/old/registry_file
+-------------------------------------------------------------------------------------
+
+The registry will be migrated to the new location only if a registry using the
+directory format does not already exist.
+
 
 [float]
 ==== `config_dir`
diff --git a/filebeat/filebeat.reference.yml b/filebeat/filebeat.reference.yml
index 352e575eeecb..ff8a5b0b050e 100644
--- a/filebeat/filebeat.reference.yml
+++ b/filebeat/filebeat.reference.yml
@@ -800,6 +800,14 @@ filebeat.inputs:
 # batch of events has been published successfully. The default value is 0s.
 #filebeat.registry.flush: 0s
 
+
+# Starting with Filebeat 7.0, the registry uses a new directory format to store
+# Filebeat state. After you upgrade, Filebeat will automatically migrate a 6.x
+# registry file to use the new directory format. If you changed
+# filebeat.registry.path while upgrading, set filebeat.registry.migrate_file to
+# point to the old registry file.
+#filebeat.registry.migrate_file: ${path.data}/registry
+
 # By default Ingest pipelines are not updated if a pipeline with the same ID
 # already exists. If this option is enabled Filebeat overwrites pipelines
 # everytime a new Elasticsearch connection is established.
diff --git a/x-pack/filebeat/filebeat.reference.yml b/x-pack/filebeat/filebeat.reference.yml
index 484c46b2b7a8..6cf32cc03e85 100644
--- a/x-pack/filebeat/filebeat.reference.yml
+++ b/x-pack/filebeat/filebeat.reference.yml
@@ -906,6 +906,14 @@ filebeat.inputs:
 # batch of events has been published successfully. The default value is 0s.
 #filebeat.registry.flush: 0s
 
+
+# Starting with Filebeat 7.0, the registry uses a new directory format to store
+# Filebeat state. After you upgrade, Filebeat will automatically migrate a 6.x
+# registry file to use the new directory format. If you changed
+# filebeat.registry.path while upgrading, set filebeat.registry.migrate_file to
+# point to the old registry file.
+#filebeat.registry.migrate_file: ${path.data}/registry
+
 # By default Ingest pipelines are not updated if a pipeline with the same ID
 # already exists. If this option is enabled Filebeat overwrites pipelines
 # everytime a new Elasticsearch connection is established.