1 files changed, 83 insertions, 6 deletions
diff --git a/collectors/plugins.d/README.md b/collectors/plugins.d/README.md
index 8ad1d3a6..1c3b50cb 100644
--- a/collectors/plugins.d/README.md
+++ b/collectors/plugins.d/README.md
@@ -1,13 +1,13 @@
 <!--
-title: "External plugins overview"
+title: "External plugins"
 custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/plugins.d/README.md"
-sidebar_label: "External plugins overview"
+sidebar_label: "External plugins"
 learn_status: "Published"
 learn_topic_type: "References"
-learn_rel_path: "Developers"
+learn_rel_path: "Developers/External plugins"
 -->
 
-# External plugins overview
+# External plugins
 
 `plugins.d` is the Netdata internal plugin that collects metrics
 from external processes, thus allowing Netdata to use **external plugins**.
@@ -138,7 +138,7 @@ a single program can produce any number of charts with any number of dimensions
 
 Charts can be added any time (not just the beginning).
 
-### command line parameters
+### Command line parameters
 
 The plugin **MUST** accept just **one** parameter: **the number of seconds it is
 expected to update the values for its charts**. The value passed by Netdata
@@ -149,7 +149,7 @@ The external plugin can overwrite the update frequency. For example, the server
 request per second updates, but the plugin may ignore it and update its charts
 every 5 seconds.
 
-### environment variables
+### Environment variables
 
 There are a few environment variables that are set by `netdata` and are
 available for the plugin to use.
@@ -175,6 +175,83 @@ The plugin should output instructions for Netdata to its output (`stdout`). Sinc
 
 `DISABLE` will disable this plugin. This will prevent Netdata from restarting the plugin. You can also exit with the value `1` to have the same effect.
 
+#### HOST_DEFINE
+
+`HOST_DEFINE` defines a new (or updates an existing) virtual host.
+
+The template is:
+
+> HOST_DEFINE machine_guid hostname
+
+where:
+
+-   `machine_guid`
+
+    uniquely identifies the host, this is what will be needed to add charts to the host.
+
+-   `hostname`
+
+    is the hostname of the virtual host
+
+#### HOST_LABEL
+
+`HOST_LABEL` adds a key-value pair to the virtual host labels. It has to be given between `HOST_DEFINE` and `HOST_DEFINE_END`.
+
+The template is:
+
+> HOST_LABEL key value
+
+where:
+
+-   `key`
+
+    uniquely identifies the key of the label
+
+-   `value`
+
+    is the value associated with this key
+
+There are a few special keys that are used to define the system information of the monitored system:
+
+- `_cloud_provider_type`
+- `_cloud_instance_type`
+- `_cloud_instance_region`
+- `_os_name`
+- `_os_version`
+- `_kernel_version`
+- `_system_cores`
+- `_system_cpu_freq`
+- `_system_ram_total`
+- `_system_disk_space`
+- `_architecture`
+- `_virtualization`
+- `_container`
+- `_container_detection`
+- `_virt_detection`
+- `_is_k8s_node`
+- `_install_type`
+- `_prebuilt_arch`
+- `_prebuilt_dist`
+
+#### HOST_DEFINE_END
+
+`HOST_DEFINE_END` commits the host information, creating a new host entity, or updating an existing one with the same `machine_guid`.
+
+#### HOST 
+
+`HOST` switches data collection between hosts.
+
+The template is:
+
+> HOST machine_guid
+
+where:
+
+-   `machine_guid`
+
+    is the UUID of the host to switch to. After this command, every other command following it is assumed to be associated with this host.
+    Setting machine_guid to `localhost` switches data collection to the local host.
+
 #### CHART
 
 `CHART` defines a new chart.