Adding upstream version 1.44.3.upstream/1.44.3upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

13 files changed, 2473 insertions, 0 deletions

diff --git a/registry/Makefile.am b/registry/Makefile.am
new file mode 100644
index 00000000..161784b8
--- /dev/null
+++ b/registry/Makefile.am
@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+AUTOMAKE_OPTIONS = subdir-objects
+MAINTAINERCLEANFILES = $(srcdir)/Makefile.in
+
+dist_noinst_DATA = \
+    README.md \
+    $(NULL)
diff --git a/registry/README.md b/registry/README.md
new file mode 100644
index 00000000..0bf174e1
--- /dev/null
+++ b/registry/README.md
@@ -0,0 +1,217 @@
+<!--
+title: "Registry"
+description: "Netdata utilizes a central registry of machines/person GUIDs, URLs, and opt-in account information to provide unified cross-server dashboards."
+custom_edit_url: "https://github.com/netdata/netdata/edit/master/registry/README.md"
+sidebar_label: "Registry"
+learn_status: "Published"
+learn_rel_path: "Configuration"
+-->
+
+# Registry
+
+Netdata provides distributed monitoring.
+
+Traditional monitoring solutions centralize all the data to provide unified dashboards across all servers. Before
+Netdata, this was the standard practice. However it has a few issues:
+
+1.  due to the resources required, the number of metrics collected is limited.
+2.  for the same reason, the data collection frequency is not that high, at best it will be once every 10 or 15 seconds,
+    at worst every 5 or 10 mins.
+3.  the central monitoring solution needs dedicated resources, thus becoming "another bottleneck" in the whole
+    ecosystem. It also requires maintenance, administration, etc.
+4.  most centralized monitoring solutions are usually only good for presenting _statistics of past performance_ (i.e.
+    cannot be used for real-time performance troubleshooting).
+
+Netdata follows a different approach:
+
+1.  data collection happens per second
+2.  thousands of metrics per server are collected
+3.  data do not leave the server where they are collected
+4.  Netdata servers do not talk to each other
+5.  your browser connects all the Netdata servers
+
+Using Netdata, your monitoring infrastructure is embedded on each server, limiting significantly the need of additional
+resources. Netdata is blazingly fast, very resource efficient and utilizes server resources that already exist and are
+spare (on each server). This allows **scaling out** the monitoring infrastructure.
+
+However, the Netdata approach introduces a few new issues that need to be addressed, one being **the list of Netdata we
+have installed**, i.e. the URLs our Netdata servers are listening.
+
+To solve this, Netdata utilizes a **central registry**. This registry, together with certain browser features, allow
+Netdata to provide unified cross-server dashboards. For example, when you jump from server to server using the node
+menu, several session settings (like the currently viewed charts, the current zoom and pan operations on the charts,
+etc.) are propagated to the new server, so that the new dashboard will come with exactly the same view.
+
+## What data does the registry store?
+
+The registry keeps track of 4 entities:
+
+1.  **machines**: i.e. the Netdata installations (a random GUID generated by each Netdata the first time it starts; we
+    call this **machine_guid**)
+
+  For each Netdata installation (each `machine_guid`) the registry keeps track of the different URLs it has accessed.
+
+2.  **persons**: i.e. the web browsers accessing the Netdata installations (a random GUID generated by the registry the
+    first time it sees a new web browser; we call this **person_guid**)
+
+  For each person, the registry keeps track of the Netdata installations it has accessed and their URLs. 
+
+3.  **URLs** of Netdata installations (as seen by the web browsers)
+
+  For each URL, the registry keeps the URL and nothing more. Each URL is linked to _persons_ and _machines_. The only
+  way to find a URL is to know its **machine_guid** or have a **person_guid** it is linked to it.
+
+4.  **accounts**: i.e. the information used to sign-in via one of the available sign-in methods. Depending on the
+    method, this may include an email, or an email and a profile picture or avatar.
+
+For _persons_/_accounts_ and _machines_, the registry keeps links to _URLs_, each link with 2 timestamps (first time
+seen, last time seen) and a counter (number of times it has been seen). *machines_, _persons_ and timestamps are stored
+in the Netdata registry regardless of whether you sign in or not. 
+
+## Who talks to the registry?
+
+Your web browser **only**! If sending this information is against your policies, you 
+can [run your own registry](#run-your-own-registry)
+
+Your Netdata servers do not talk to the registry. This is a UML diagram of its operation:
+
+![registry](https://cloud.githubusercontent.com/assets/2662304/19448565/11a70632-94ab-11e6-9d80-f410b4acb797.png)
+
+## Which is the default registry?
+
+`https://registry.my-netdata.io`, which is currently served by `https://london.my-netdata.io`. This registry listens to
+both HTTP and HTTPS requests but the default is HTTPS.
+
+### Can this registry handle the global load of Netdata installations?
+
+Yeap! The registry can handle 50.000 - 100.000 requests **per second per core** (depending on the type of CPU, the
+computer's memory bandwidth, etc). 50.000 is on J1900 (celeron 2Ghz).
+
+We believe, it can do it...
+
+## Run your own registry
+
+**Every Netdata can be a registry**. Just pick one and configure it.
+
+**To turn any Netdata into a registry**, edit `/etc/netdata/netdata.conf` and set:
+
+```conf
+[registry]
+    enabled = yes
+    registry to announce = http://your.registry:19999
+```
+
+Restart your Netdata to activate it.
+
+Then, you need to tell **all your other Netdata servers to advertise your registry**, instead of the default. To do
+this, on each of your Netdata servers, edit `/etc/netdata/netdata.conf` and set:
+
+```conf
+[registry]
+    enabled = no
+    registry to announce = http://your.registry:19999
+```
+
+Note that we have not enabled the registry on the other servers. Only one Netdata (the registry) needs
+`[registry].enabled = yes`.
+
+This is it. You have your registry now.
+
+You may also want to give your server different names under the node menu (i.e. to have them sorted / grouped). You can
+change its registry name, by setting on each Netdata server:
+
+```conf
+[registry]
+    registry hostname = Group1 - Master DB
+```
+
+So this server will appear in the node menu as `Group1 - Master DB`. The max name length is 50 characters.
+
+### Limiting access to the registry
+
+Netdata v1.9+ support limiting access to the registry from given IPs, like this:
+
+```conf
+[registry]
+    allow from = *
+```
+
+`allow from` settings are [Netdata simple patterns](https://github.com/netdata/netdata/blob/master/libnetdata/simple_pattern/README.md): string matches that use `*`
+as wildcard (any number of times) and a `!` prefix for a negative match. So: `allow from = !10.1.2.3 10.*` will allow
+all IPs in `10.*` except `10.1.2.3`. The order is important: left to right, the first positive or negative match is
+used.
+
+Keep in mind that connections to Netdata API ports are filtered by `[web].allow connections from`. So, IPs allowed by
+`[registry].allow from` should also be allowed by `[web].allow connection from`.
+
+The patterns can be matches over IP addresses or FQDN of the host. In order to check the FQDN of the connection without
+opening the Netdata agent to DNS-spoofing, a reverse-dns record must be setup for the connecting host. At connection
+time the reverse-dns of the peer IP address is resolved, and a forward DNS resolution is made to validate the IP address
+against the name-pattern.
+
+Please note that this process can be expensive on a machine that is serving many connections. The behaviour of the
+pattern matching can be controlled with the following setting:
+
+```conf
+[registry]
+    allow by dns = heuristic
+```
+
+The settings are:
+-   `yes` allows the pattern to match DNS names.
+-   `no` disables DNS matching for the patterns (they only match IP addresses).
+-   `heuristic` will estimate if the patterns should match FQDNs by the presence or absence of `:`s or alpha-characters.
+
+### Where is the registry database stored?
+
+`/var/lib/netdata/registry/*.db`
+
+There can be up to 2 files:
+
+-   `registry-log.db`, the transaction log
+
+      all incoming requests that affect the registry are saved in this file in real-time.
+
+-   `registry.db`, the database
+
+      every `[registry].registry save db every new entries` entries in `registry-log.db`, Netdata will save its database
+      to `registry.db` and empty `registry-log.db`.
+
+Both files are machine readable text files.
+
+### How can I disable the SameSite and Secure cookies?
+
+Beginning with `v1.30.0`, when the Netdata Agent's web server processes a request, it delivers the `SameSite=none`
+and `Secure` cookies. If you have problems accessing the local Agent dashboard or Netdata Cloud, disable these
+cookies by [editing `netdata.conf`](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#use-edit-config-to-edit-configuration-files):
+
+```conf
+[registry]
+    enable cookies SameSite and Secure = no
+```
+
+## The future
+
+The registry opens a whole world of new possibilities for Netdata. Check here what we think:
+<https://github.com/netdata/netdata/issues/416>
+
+## Troubleshooting the registry
+
+The registry URL should be set to the URL of a Netdata dashboard. This server has to have `[registry].enabled = yes`.
+So, accessing the registry URL directly with your web browser, should present the dashboard of the Netdata operating the
+registry.
+
+To use the registry, your web browser needs to support **third party cookies**, since the cookies are set by the
+registry while you are browsing the dashboard of another Netdata server. The registry, the first time it sees a new web
+browser it tries to figure if the web browser has cookies enabled or not. It does this by setting a cookie and
+redirecting the browser back to itself hoping that it will receive the cookie. If it does not receive the cookie, the
+registry will keep redirecting your web browser back to itself, which after a few redirects will fail with an error like
+this:
+
+```conf
+ERROR 409: Cannot ACCESS netdata registry: https://registry.my-netdata.io responded with: {"status":"redirect","registry":"https://registry.my-netdata.io"}
+```
+
+This error is printed on your web browser console (press F12 on your browser to see it).
+
+
diff --git a/registry/registry.c b/registry/registry.c
new file mode 100644
index 00000000..3f3c4b27
--- /dev/null
+++ b/registry/registry.c
@@ -0,0 +1,535 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+#include "daemon/common.h"
+#include "registry_internals.h"
+
+#define REGISTRY_STATUS_OK "ok"
+#define REGISTRY_STATUS_REDIRECT "redirect"
+#define REGISTRY_STATUS_FAILED "failed"
+#define REGISTRY_STATUS_DISABLED "disabled"
+
+bool registry_is_valid_url(const char *url) {
+    return url && (*url == 'h' || *url == '*');
+}
+
+// ----------------------------------------------------------------------------
+// REGISTRY concurrency locking
+
+static inline void registry_lock(void) {
+    netdata_mutex_lock(&registry.lock);
+}
+
+static inline void registry_unlock(void) {
+    netdata_mutex_unlock(&registry.lock);
+}
+
+// ----------------------------------------------------------------------------
+// COOKIES
+
+static void registry_set_cookie(struct web_client *w, const char *guid) {
+    char rfc7231_expires[RFC7231_MAX_LENGTH];
+    rfc7231_datetime(rfc7231_expires, sizeof(rfc7231_expires), now_realtime_sec() + registry.persons_expiration);
+
+    buffer_sprintf(w->response.header, "Set-Cookie: " NETDATA_REGISTRY_COOKIE_NAME "=%s; Expires=%s\r\n", guid, rfc7231_expires);
+    buffer_sprintf(w->response.header, "Set-Cookie: " NETDATA_REGISTRY_COOKIE_NAME "=%s; SameSite=Strict; Expires=%s\r\n", guid, rfc7231_expires);
+    if(registry.enable_cookies_samesite_secure)
+        buffer_sprintf(w->response.header, "Set-Cookie: " NETDATA_REGISTRY_COOKIE_NAME "=%s; Expires=%s; SameSite=None; Secure\r\n", guid, rfc7231_expires);
+
+    if(registry.registry_domain && *registry.registry_domain) {
+        buffer_sprintf(w->response.header, "Set-Cookie: " NETDATA_REGISTRY_COOKIE_NAME "=%s; Expires=%s; Domain=%s\r\n", guid, rfc7231_expires, registry.registry_domain);
+        buffer_sprintf(w->response.header, "Set-Cookie: " NETDATA_REGISTRY_COOKIE_NAME "=%s; Expires=%s; Domain=%s; SameSite=Strict\r\n", guid, rfc7231_expires, registry.registry_domain);
+        if(registry.enable_cookies_samesite_secure)
+            buffer_sprintf(w->response.header, "Set-Cookie: " NETDATA_REGISTRY_COOKIE_NAME "=%s; Expires=%s; Domain=%s; SameSite=None; Secure\r\n", guid, rfc7231_expires, registry.registry_domain);
+    }
+
+    w->response.has_cookies = true;
+}
+
+static inline void registry_set_person_cookie(struct web_client *w, REGISTRY_PERSON *p) {
+    registry_set_cookie(w, p->guid);
+}
+
+
+// ----------------------------------------------------------------------------
+// JSON GENERATION
+
+static inline void registry_json_header(RRDHOST *host, struct web_client *w, const char *action, const char *status) {
+    buffer_flush(w->response.data);
+    w->response.data->content_type = CT_APPLICATION_JSON;
+    buffer_json_initialize(w->response.data, "\"", "\"", 0, true, BUFFER_JSON_OPTIONS_DEFAULT);
+    buffer_json_member_add_string(w->response.data, "action", action);
+    buffer_json_member_add_string(w->response.data, "status", status);
+    buffer_json_member_add_string(w->response.data, "hostname", rrdhost_registry_hostname(host));
+    buffer_json_member_add_string(w->response.data, "machine_guid", host->machine_guid);
+}
+
+static inline void registry_json_footer(struct web_client *w) {
+    buffer_json_finalize(w->response.data);
+}
+
+static inline int registry_json_disabled(RRDHOST *host, struct web_client *w, const char *action) {
+    registry_json_header(host, w, action, REGISTRY_STATUS_DISABLED);
+
+    buffer_json_member_add_string(w->response.data, "registry", registry.registry_to_announce);
+
+    registry_json_footer(w);
+    return HTTP_RESP_OK;
+}
+
+
+// ----------------------------------------------------------------------------
+// CALLBACKS FOR WALKING THROUGH REGISTRY OBJECTS
+
+// structure used be the callbacks below
+struct registry_json_walk_person_urls_callback {
+    REGISTRY_PERSON *p;
+    REGISTRY_MACHINE *m;
+    struct web_client *w;
+    int count;
+};
+
+static STRING *asterisks = NULL;
+
+// callback for rendering PERSON_URLs
+static int registry_json_person_url_callback(REGISTRY_PERSON_URL *pu, struct registry_json_walk_person_urls_callback *c) {
+    if(unlikely(!asterisks))
+        asterisks = string_strdupz("***");
+
+    struct web_client *w = c->w;
+
+    if (pu->url == asterisks) return 0;
+
+    buffer_json_add_array_item_array(w->response.data);
+    buffer_json_add_array_item_string(w->response.data, pu->machine->guid);
+    buffer_json_add_array_item_string(w->response.data, string2str(pu->url));
+    buffer_json_add_array_item_uint64(w->response.data, pu->last_t * (uint64_t) 1000);
+    buffer_json_add_array_item_uint64(w->response.data, pu->usages);
+    buffer_json_add_array_item_string(w->response.data, string2str(pu->machine_name));
+    buffer_json_array_close(w->response.data);
+
+    return 1;
+}
+
+// callback for rendering MACHINE_URLs
+static int registry_json_machine_url_callback(REGISTRY_MACHINE_URL *mu, struct registry_json_walk_person_urls_callback *c, STRING *hostname) {
+    if(unlikely(!asterisks))
+        asterisks = string_strdupz("***");
+
+    struct web_client *w = c->w;
+    REGISTRY_MACHINE *m = c->m;
+
+    if (mu->url == asterisks) return 0;
+
+    buffer_json_add_array_item_array(w->response.data);
+    buffer_json_add_array_item_string(w->response.data, m->guid);
+    buffer_json_add_array_item_string(w->response.data, string2str(mu->url));
+    buffer_json_add_array_item_uint64(w->response.data, mu->last_t * (uint64_t) 1000);
+    buffer_json_add_array_item_uint64(w->response.data, mu->usages);
+    buffer_json_add_array_item_string(w->response.data, string2str(hostname));
+    buffer_json_array_close(w->response.data);
+
+    return 1;
+}
+
+// ----------------------------------------------------------------------------
+
+// structure used be the callbacks below
+struct registry_person_url_callback_verify_machine_exists_data {
+    REGISTRY_MACHINE *m;
+    int count;
+};
+
+static inline int registry_person_url_callback_verify_machine_exists(REGISTRY_PERSON_URL *pu, struct registry_person_url_callback_verify_machine_exists_data *d) {
+    REGISTRY_MACHINE *m = d->m;
+
+    if(pu->machine == m)
+        d->count++;
+
+    return 0;
+}
+
+// ----------------------------------------------------------------------------
+// dynamic update of the configuration
+// The registry does not seem to be designed to support this and I cannot see any concurrency protection
+// that could make this safe, so try to be as atomic as possible.
+
+void registry_update_cloud_base_url() {
+    registry.cloud_base_url = appconfig_get(&cloud_config, CONFIG_SECTION_GLOBAL, "cloud base url", DEFAULT_CLOUD_BASE_URL);
+    setenv("NETDATA_REGISTRY_CLOUD_BASE_URL", registry.cloud_base_url, 1);
+}
+
+// ----------------------------------------------------------------------------
+// public HELLO request
+
+int registry_request_hello_json(RRDHOST *host, struct web_client *w, bool do_not_track) {
+    registry_json_header(host, w, "hello", REGISTRY_STATUS_OK);
+
+    if(host->node_id)
+        buffer_json_member_add_uuid(w->response.data, "node_id", host->node_id);
+
+    buffer_json_member_add_object(w->response.data, "agent");
+    {
+        buffer_json_member_add_string(w->response.data, "machine_guid", localhost->machine_guid);
+
+        if(localhost->node_id)
+            buffer_json_member_add_uuid(w->response.data, "node_id", localhost->node_id);
+
+        char *claim_id = get_agent_claimid();
+        if (claim_id) {
+            buffer_json_member_add_string(w->response.data, "claim_id", claim_id);
+            freez(claim_id);
+        }
+
+        buffer_json_member_add_boolean(w->response.data, "bearer_protection", netdata_is_protected_by_bearer);
+    }
+    buffer_json_object_close(w->response.data);
+
+    CLOUD_STATUS status = cloud_status();
+    buffer_json_member_add_string(w->response.data, "cloud_status", cloud_status_to_string(status));
+    buffer_json_member_add_string(w->response.data, "cloud_base_url", registry.cloud_base_url);
+
+    buffer_json_member_add_string(w->response.data, "registry", registry.registry_to_announce);
+    buffer_json_member_add_boolean(w->response.data, "anonymous_statistics", do_not_track ? false : netdata_anonymous_statistics_enabled);
+    buffer_json_member_add_boolean(w->response.data, "X-Netdata-Auth", true);
+
+    buffer_json_member_add_array(w->response.data, "nodes");
+    RRDHOST *h;
+    dfe_start_read(rrdhost_root_index, h) {
+        buffer_json_add_array_item_object(w->response.data);
+        buffer_json_member_add_string(w->response.data, "machine_guid", h->machine_guid);
+
+        if(h->node_id)
+            buffer_json_member_add_uuid(w->response.data, "node_id", h->node_id);
+
+        buffer_json_member_add_string(w->response.data, "hostname", rrdhost_registry_hostname(h));
+        buffer_json_object_close(w->response.data);
+    }
+    dfe_done(h);
+    buffer_json_array_close(w->response.data); // nodes
+
+    registry_json_footer(w);
+    return HTTP_RESP_OK;
+}
+
+// ----------------------------------------------------------------------------
+// public ACCESS request
+
+// the main method for registering an access
+int registry_request_access_json(RRDHOST *host, struct web_client *w, char *person_guid, char *machine_guid, char *url, char *name, time_t when) {
+    if(unlikely(!registry.enabled))
+        return registry_json_disabled(host, w, "access");
+
+    if(!registry_is_valid_url(url)) {
+        buffer_flush(w->response.data);
+        buffer_strcat(w->response.data, "Invalid URL given in the request");
+        return HTTP_RESP_BAD_REQUEST;
+    }
+
+    // ------------------------------------------------------------------------
+    // verify the browser supports cookies or the bearer
+
+    if(registry.verify_cookies_redirects > 0 && !person_guid[0]) {
+        registry_lock();
+        registry_request_access(REGISTRY_VERIFY_COOKIES_GUID, machine_guid, url, name, when);
+        registry_unlock();
+
+        buffer_flush(w->response.data);
+        registry_set_cookie(w, REGISTRY_VERIFY_COOKIES_GUID);
+        w->response.data->content_type = CT_APPLICATION_JSON;
+        registry_json_header(host, w, "access", REGISTRY_STATUS_REDIRECT);
+        buffer_json_member_add_string(w->response.data, "person_guid", REGISTRY_VERIFY_COOKIES_GUID);
+        buffer_json_member_add_string(w->response.data, "registry", registry.registry_to_announce);
+        registry_json_footer(w);
+        return HTTP_RESP_OK;
+    }
+
+    if(unlikely(person_guid[0] && is_dummy_person(person_guid)))
+        // it passed the check - they gave us a different person_guid
+        // empty the dummy one, so that we will generate a new person_guid
+        person_guid[0] = '\0';
+
+    // ------------------------------------------------------------------------
+
+    registry_lock();
+
+    REGISTRY_PERSON *p = registry_request_access(person_guid, machine_guid, url, name, when);
+    if(!p) {
+        registry_json_header(host, w, "access", REGISTRY_STATUS_FAILED);
+        registry_json_footer(w);
+        registry_unlock();
+        return HTTP_RESP_PRECOND_FAIL;
+    }
+
+    // set the cookie
+    registry_set_person_cookie(w, p);
+
+    // generate the response
+    registry_json_header(host, w, "access", REGISTRY_STATUS_OK);
+    buffer_json_member_add_string(w->response.data, "person_guid", p->guid);
+    buffer_json_member_add_array(w->response.data, "urls");
+
+    struct registry_json_walk_person_urls_callback c = { p, NULL, w, 0 };
+    for(REGISTRY_PERSON_URL *pu = p->person_urls; pu ;pu = pu->next)
+        registry_json_person_url_callback(pu, &c);
+    buffer_json_array_close(w->response.data); // urls
+
+    registry_json_footer(w);
+    registry_unlock();
+    return HTTP_RESP_OK;
+}
+
+// ----------------------------------------------------------------------------
+// public DELETE request
+
+// the main method for deleting a URL from a person
+int registry_request_delete_json(RRDHOST *host, struct web_client *w, char *person_guid, char *machine_guid, char *url, char *delete_url, time_t when) {
+    if(!registry.enabled)
+        return registry_json_disabled(host, w, "delete");
+
+    if(!registry_is_valid_url(url)) {
+        buffer_flush(w->response.data);
+        buffer_strcat(w->response.data, "Invalid URL given in the request");
+        return HTTP_RESP_BAD_REQUEST;
+    }
+
+    registry_lock();
+
+    REGISTRY_PERSON *p = registry_request_delete(person_guid, machine_guid, url, delete_url, when);
+    if(!p) {
+        registry_json_header(host, w, "delete", REGISTRY_STATUS_FAILED);
+        registry_json_footer(w);
+        registry_unlock();
+        return HTTP_RESP_PRECOND_FAIL;
+    }
+
+    // generate the response
+    registry_json_header(host, w, "delete", REGISTRY_STATUS_OK);
+    registry_json_footer(w);
+    registry_unlock();
+    return HTTP_RESP_OK;
+}
+
+// ----------------------------------------------------------------------------
+// public SEARCH request
+
+// the main method for searching the URLs of a netdata
+int registry_request_search_json(RRDHOST *host, struct web_client *w, char *person_guid, char *request_machine) {
+    if(!registry.enabled)
+        return registry_json_disabled(host, w, "search");
+
+    if(!person_guid || !person_guid[0]) {
+        registry_json_header(host, w, "search", REGISTRY_STATUS_FAILED);
+        registry_json_footer(w);
+        return HTTP_RESP_PRECOND_FAIL;
+    }
+
+    registry_lock();
+
+    STRING *hostname = NULL;
+    REGISTRY_MACHINE *m = registry_request_machine(person_guid, request_machine, &hostname);
+    if(!m) {
+        registry_json_header(host, w, "search", REGISTRY_STATUS_FAILED);
+        registry_json_footer(w);
+        registry_unlock();
+        string_freez(hostname);
+        return HTTP_RESP_NOT_FOUND;
+    }
+
+    registry_json_header(host, w, "search", REGISTRY_STATUS_OK);
+
+    buffer_json_member_add_array(w->response.data, "urls");
+    struct registry_json_walk_person_urls_callback c = { NULL, m, w, 0 };
+
+    for(REGISTRY_MACHINE_URL *mu = m->machine_urls; mu ; mu = mu->next)
+        registry_json_machine_url_callback(mu, &c, hostname);
+
+    buffer_json_array_close(w->response.data);
+
+    registry_json_footer(w);
+    registry_unlock();
+    string_freez(hostname);
+    return HTTP_RESP_OK;
+}
+
+// ----------------------------------------------------------------------------
+// SWITCH REQUEST
+
+// the main method for switching user identity
+int registry_request_switch_json(RRDHOST *host, struct web_client *w, char *person_guid, char *machine_guid, char *url __maybe_unused, char *new_person_guid, time_t when __maybe_unused) {
+    if(!registry.enabled)
+        return registry_json_disabled(host, w, "switch");
+
+    if(!person_guid || !person_guid[0]) {
+        buffer_flush(w->response.data);
+        buffer_strcat(w->response.data, "Who are you? Person GUID is missing");
+        return HTTP_RESP_PRECOND_FAIL;
+    }
+
+    if(!registry_is_valid_url(url)) {
+        buffer_flush(w->response.data);
+        buffer_strcat(w->response.data, "Invalid URL given in the request");
+        return HTTP_RESP_BAD_REQUEST;
+    }
+
+    registry_lock();
+
+    REGISTRY_PERSON *op = registry_person_find(person_guid);
+    if(!op) {
+        registry_json_header(host, w, "switch", REGISTRY_STATUS_FAILED);
+        registry_json_footer(w);
+        registry_unlock();
+        return 430;
+    }
+
+    REGISTRY_PERSON *np = registry_person_find(new_person_guid);
+    if(!np) {
+        registry_json_header(host, w, "switch", REGISTRY_STATUS_FAILED);
+        registry_json_footer(w);
+        registry_unlock();
+        return 431;
+    }
+
+    REGISTRY_MACHINE *m = registry_machine_find(machine_guid);
+    if(!m) {
+        registry_json_header(host, w, "switch", REGISTRY_STATUS_FAILED);
+        registry_json_footer(w);
+        registry_unlock();
+        return 432;
+    }
+
+    struct registry_person_url_callback_verify_machine_exists_data data = { m, 0 };
+
+    // verify the old person has access to this machine
+    for(REGISTRY_PERSON_URL *pu = op->person_urls; pu ;pu = pu->next)
+        registry_person_url_callback_verify_machine_exists(pu, &data);
+
+    if(!data.count) {
+        registry_json_header(host, w, "switch", REGISTRY_STATUS_FAILED);
+        registry_json_footer(w);
+        registry_unlock();
+        return 433;
+    }
+
+    // verify the new person has access to this machine
+    data.count = 0;
+    for(REGISTRY_PERSON_URL *pu = np->person_urls; pu ;pu = pu->next)
+        registry_person_url_callback_verify_machine_exists(pu, &data);
+
+    if(!data.count) {
+        registry_json_header(host, w, "switch", REGISTRY_STATUS_FAILED);
+        registry_json_footer(w);
+        registry_unlock();
+        return 434;
+    }
+
+    // set the cookie of the new person
+    // the user just switched identity
+    registry_set_person_cookie(w, np);
+
+    // generate the response
+    registry_json_header(host, w, "switch", REGISTRY_STATUS_OK);
+    buffer_json_member_add_string(w->response.data, "person_guid", np->guid);
+    registry_json_footer(w);
+
+    registry_unlock();
+    return HTTP_RESP_OK;
+}
+
+// ----------------------------------------------------------------------------
+// STATISTICS
+
+void registry_statistics(void) {
+    if(!registry.enabled) return;
+
+    static RRDSET *sts = NULL, *stc = NULL, *stm = NULL;
+
+    if(unlikely(!sts)) {
+        sts = rrdset_create_localhost(
+                "netdata"
+                , "registry_sessions"
+                , NULL
+                , "registry"
+                , NULL
+                , "Netdata Registry Sessions"
+                , "sessions"
+                , "registry"
+                , "stats"
+                , 131000
+                , localhost->rrd_update_every
+                , RRDSET_TYPE_LINE
+        );
+
+        rrddim_add(sts, "sessions",  NULL,  1, 1, RRD_ALGORITHM_ABSOLUTE);
+    }
+
+    rrddim_set(sts, "sessions", (collected_number)registry.usages_count);
+    rrdset_done(sts);
+
+    // ------------------------------------------------------------------------
+
+    if(unlikely(!stc)) {
+        stc = rrdset_create_localhost(
+                "netdata"
+                , "registry_entries"
+                , NULL
+                , "registry"
+                , NULL
+                , "Netdata Registry Entries"
+                , "entries"
+                , "registry"
+                , "stats"
+                , 131100
+                , localhost->rrd_update_every
+                , RRDSET_TYPE_LINE
+        );
+
+        rrddim_add(stc, "persons",        NULL,  1, 1, RRD_ALGORITHM_ABSOLUTE);
+        rrddim_add(stc, "machines",       NULL,  1, 1, RRD_ALGORITHM_ABSOLUTE);
+        rrddim_add(stc, "persons_urls",   NULL,  1, 1, RRD_ALGORITHM_ABSOLUTE);
+        rrddim_add(stc, "machines_urls",  NULL,  1, 1, RRD_ALGORITHM_ABSOLUTE);
+    }
+
+    rrddim_set(stc, "persons",       (collected_number)registry.persons_count);
+    rrddim_set(stc, "machines",      (collected_number)registry.machines_count);
+    rrddim_set(stc, "persons_urls",  (collected_number)registry.persons_urls_count);
+    rrddim_set(stc, "machines_urls", (collected_number)registry.machines_urls_count);
+    rrdset_done(stc);
+
+    // ------------------------------------------------------------------------
+
+    if(unlikely(!stm)) {
+        stm = rrdset_create_localhost(
+                "netdata"
+                , "registry_mem"
+                , NULL
+                , "registry"
+                , NULL
+                , "Netdata Registry Memory"
+                , "KiB"
+                , "registry"
+                , "stats"
+                , 131300
+                , localhost->rrd_update_every
+                , RRDSET_TYPE_STACKED
+        );
+
+        rrddim_add(stm, "persons",        NULL,  1, 1024, RRD_ALGORITHM_ABSOLUTE);
+        rrddim_add(stm, "machines",       NULL,  1, 1024, RRD_ALGORITHM_ABSOLUTE);
+        rrddim_add(stm, "persons_urls",   NULL,  1, 1024, RRD_ALGORITHM_ABSOLUTE);
+        rrddim_add(stm, "machines_urls",  NULL,  1, 1024, RRD_ALGORITHM_ABSOLUTE);
+    }
+
+    struct aral_statistics *p_aral_stats = aral_statistics(registry.persons_aral);
+    rrddim_set(stm, "persons",       (collected_number)p_aral_stats->structures.allocated_bytes + (collected_number)p_aral_stats->malloc.allocated_bytes + (collected_number)p_aral_stats->mmap.allocated_bytes);
+
+    struct aral_statistics *m_aral_stats = aral_statistics(registry.machines_aral);
+    rrddim_set(stm, "machines",      (collected_number)m_aral_stats->structures.allocated_bytes + (collected_number)m_aral_stats->malloc.allocated_bytes + (collected_number)m_aral_stats->mmap.allocated_bytes);
+
+    struct aral_statistics *pu_aral_stats = aral_statistics(registry.person_urls_aral);
+    rrddim_set(stm, "persons_urls",  (collected_number)pu_aral_stats->structures.allocated_bytes + (collected_number)pu_aral_stats->malloc.allocated_bytes + (collected_number)pu_aral_stats->mmap.allocated_bytes);
+
+    struct aral_statistics *mu_aral_stats = aral_statistics(registry.machine_urls_aral);
+    rrddim_set(stm, "machines_urls", (collected_number)mu_aral_stats->structures.allocated_bytes + (collected_number)mu_aral_stats->malloc.allocated_bytes + (collected_number)mu_aral_stats->mmap.allocated_bytes);
+
+    rrdset_done(stm);
+}
diff --git a/registry/registry.h b/registry/registry.h
new file mode 100644
index 00000000..746fe430
--- /dev/null
+++ b/registry/registry.h
@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+/*
+ * netdata registry
+ *
+ * this header file describes the public interface
+ * to the netdata registry
+ *
+ * only these high level functions are exposed
+ *
+ */
+
+// ----------------------------------------------------------------------------
+// TODO
+//
+// 1. the default tracking cookie expires in 1 year, but the persons are not
+//    removed from the db - this means the database only grows - ideally the
+//    database should be cleaned in registry_db_save() for both on-disk and
+//    on-memory entries.
+//
+//    Cleanup:
+//    i. Find all the PERSONs that have expired cookie
+//    ii. For each of their PERSON_URLs:
+//     - decrement the linked MACHINE links
+//     - if the linked MACHINE has no other links, remove the linked MACHINE too
+//     - remove the PERSON_URL
+//
+// 2. add protection to prevent abusing the registry by flooding it with
+//    requests to fill the memory and crash it.
+//
+//    Possible protections:
+//    - limit the number of URLs per person
+//    - limit the number of URLs per machine
+//    - limit the number of persons
+//    - limit the number of machines
+//    - [DONE] limit the size of URLs
+//    - [DONE] limit the size of PERSON_URL names
+//    - limit the number of requests that add data to the registry,
+//      per client IP per hour
+//
+// 3. lower memory requirements
+//
+//    - embed avl structures directly into registry objects, instead of DICTIONARY
+//      [DONE for PERSON_URLs, PENDING for MACHINE_URLs]
+//    - store GUIDs in memory as UUID instead of char *
+//    - do not track persons using the demo machines only
+//      (i.e. start tracking them only when they access a non-demo machine)
+//    - [DONE] do not track custom dashboards by default
+
+#ifndef NETDATA_REGISTRY_H
+#define NETDATA_REGISTRY_H 1
+
+#include "daemon/common.h"
+
+#define NETDATA_REGISTRY_COOKIE_NAME "netdata_registry_id"
+
+// initialize the registry
+// should only happen when netdata starts
+int registry_init(void);
+
+// free all data held by the registry
+// should only happen when netdata exits
+void registry_free(void);
+
+// HTTP requests handled by the registry
+int registry_request_access_json(RRDHOST *host, struct web_client *w, char *person_guid, char *machine_guid, char *url, char *name, time_t when);
+int registry_request_delete_json(RRDHOST *host, struct web_client *w, char *person_guid, char *machine_guid, char *url, char *delete_url, time_t when);
+int registry_request_search_json(RRDHOST *host, struct web_client *w, char *person_guid, char *request_machine);
+int registry_request_switch_json(RRDHOST *host, struct web_client *w, char *person_guid, char *machine_guid, char *url, char *new_person_guid, time_t when);
+int registry_request_hello_json(RRDHOST *host, struct web_client *w, bool do_not_track);
+
+// update the registry config
+void registry_update_cloud_base_url();
+
+// update the registry monitoring charts
+void registry_statistics(void);
+
+char *registry_get_this_machine_guid(void);
+char *registry_get_mgmt_api_key(void);
+char *registry_get_this_machine_hostname(void);
+
+int regenerate_guid(const char *guid, char *result);
+
+#endif /* NETDATA_REGISTRY_H */
diff --git a/registry/registry_db.c b/registry/registry_db.c
new file mode 100644
index 00000000..448ca29d
--- /dev/null
+++ b/registry/registry_db.c
@@ -0,0 +1,381 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+#include "daemon/common.h"
+#include "registry_internals.h"
+
+int registry_db_should_be_saved(void) {
+    netdata_log_debug(D_REGISTRY, "log entries %llu, max %llu", registry.log_count, registry.save_registry_every_entries);
+    return registry.log_count > registry.save_registry_every_entries;
+}
+
+// ----------------------------------------------------------------------------
+// INTERNAL FUNCTIONS FOR SAVING REGISTRY OBJECTS
+
+static int registry_machine_save_url(REGISTRY_MACHINE_URL *mu, FILE *fp) {
+    netdata_log_debug(D_REGISTRY, "REGISTRY: registry_machine_save_url('%s')", string2str(mu->url));
+
+    int ret = fprintf(fp, "V\t%08x\t%08x\t%08x\t%02x\t%s\n",
+            mu->first_t,
+            mu->last_t,
+            mu->usages,
+            mu->flags,
+            string2str(mu->url)
+    );
+
+    // error handling is done at registry_db_save()
+
+    return ret;
+}
+
+static int registry_machine_save(const DICTIONARY_ITEM *item __maybe_unused, void *entry, void *file) {
+
+    REGISTRY_MACHINE *m = entry;
+    FILE *fp = file;
+
+    netdata_log_debug(D_REGISTRY, "REGISTRY: registry_machine_save('%s')", m->guid);
+
+    int ret = fprintf(fp, "M\t%08x\t%08x\t%08x\t%s\n",
+            m->first_t,
+            m->last_t,
+            m->usages,
+            m->guid
+    );
+
+    if(ret >= 0) {
+        for(REGISTRY_MACHINE_URL *mu = m->machine_urls; mu ; mu = mu->next) {
+            int rc = registry_machine_save_url(mu, fp);
+            if(rc < 0)
+                return rc;
+
+            ret += rc;
+        }
+    }
+
+    // error handling is done at registry_db_save()
+
+    return ret;
+}
+
+static inline int registry_person_save_url(REGISTRY_PERSON_URL *pu, FILE *fp) {
+    netdata_log_debug(D_REGISTRY, "REGISTRY: registry_person_save_url('%s')", string2str(pu->url));
+
+    int ret = fprintf(fp, "U\t%08x\t%08x\t%08x\t%02x\t%s\t%s\t%s\n",
+            pu->first_t,
+            pu->last_t,
+            pu->usages,
+            pu->flags,
+            pu->machine->guid,
+            string2str(pu->machine_name),
+            string2str(pu->url)
+    );
+
+    // error handling is done at registry_db_save()
+
+    return ret;
+}
+
+static inline int registry_person_save(const DICTIONARY_ITEM *item __maybe_unused, void *entry, void *file) {
+    REGISTRY_PERSON *p = entry;
+    FILE *fp = file;
+
+    netdata_log_debug(D_REGISTRY, "REGISTRY: registry_person_save('%s')", p->guid);
+
+    int ret = fprintf(fp, "P\t%08x\t%08x\t%08x\t%s\n",
+            p->first_t,
+            p->last_t,
+            p->usages,
+            p->guid
+    );
+
+    if(ret >= 0) {
+        for(REGISTRY_PERSON_URL *pu = p->person_urls; pu ;pu = pu->next) {
+            int rc = registry_person_save_url(pu, fp);
+            if(rc < 0)
+                return rc;
+            else
+                ret += rc;
+        }
+    }
+
+    // error handling is done at registry_db_save()
+
+    return ret;
+}
+
+// ----------------------------------------------------------------------------
+// SAVE THE REGISTRY DATABASE
+
+int registry_db_save(void) {
+    if(unlikely(!registry.enabled))
+        return -1;
+
+    if(unlikely(!registry_db_should_be_saved()))
+        return -2;
+
+    nd_log_limits_unlimited();
+
+    char tmp_filename[FILENAME_MAX + 1];
+    char old_filename[FILENAME_MAX + 1];
+
+    snprintfz(old_filename, FILENAME_MAX, "%s.old", registry.db_filename);
+    snprintfz(tmp_filename, FILENAME_MAX, "%s.tmp", registry.db_filename);
+
+    netdata_log_debug(D_REGISTRY, "REGISTRY: Creating file '%s'", tmp_filename);
+    FILE *fp = fopen(tmp_filename, "w");
+    if(!fp) {
+        netdata_log_error("REGISTRY: Cannot create file: %s", tmp_filename);
+        nd_log_limits_reset();
+        return -1;
+    }
+
+    // dictionary_walkthrough_read() has its own locking, so this is safe to do
+
+    netdata_log_debug(D_REGISTRY, "REGISTRY: saving all machines");
+    int bytes1 = dictionary_walkthrough_read(registry.machines, registry_machine_save, fp);
+    if(bytes1 < 0) {
+        netdata_log_error("REGISTRY: Cannot save registry machines - return value %d", bytes1);
+        fclose(fp);
+        nd_log_limits_reset();
+        return bytes1;
+    }
+    netdata_log_debug(D_REGISTRY, "REGISTRY: saving machines took %d bytes", bytes1);
+
+    netdata_log_debug(D_REGISTRY, "Saving all persons");
+    int bytes2 = dictionary_walkthrough_read(registry.persons, registry_person_save, fp);
+    if(bytes2 < 0) {
+        netdata_log_error("REGISTRY: Cannot save registry persons - return value %d", bytes2);
+        fclose(fp);
+        nd_log_limits_reset();
+        return bytes2;
+    }
+    netdata_log_debug(D_REGISTRY, "REGISTRY: saving persons took %d bytes", bytes2);
+
+    // save the totals
+    fprintf(fp, "T\t%016llx\t%016llx\t%016llx\t%016llx\t%016llx\t%016llx\n",
+            registry.persons_count,
+            registry.machines_count,
+            registry.usages_count + 1, // this is required - it is lost on db rotation
+            0LLU, //registry.urls_count,
+            registry.persons_urls_count,
+            registry.machines_urls_count
+    );
+
+    fclose(fp);
+
+    errno = 0;
+
+    // remove the .old db
+    netdata_log_debug(D_REGISTRY, "REGISTRY: Removing old db '%s'", old_filename);
+    if(unlink(old_filename) == -1 && errno != ENOENT)
+        netdata_log_error("REGISTRY: cannot remove old registry file '%s'", old_filename);
+
+    // rename the db to .old
+    netdata_log_debug(D_REGISTRY, "REGISTRY: Link current db '%s' to .old: '%s'", registry.db_filename, old_filename);
+    if(link(registry.db_filename, old_filename) == -1 && errno != ENOENT)
+        netdata_log_error("REGISTRY: cannot move file '%s' to '%s'. Saving registry DB failed!", registry.db_filename, old_filename);
+
+    else {
+        // remove the database (it is saved in .old)
+        netdata_log_debug(D_REGISTRY, "REGISTRY: removing db '%s'", registry.db_filename);
+        if (unlink(registry.db_filename) == -1 && errno != ENOENT)
+            netdata_log_error("REGISTRY: cannot remove old registry file '%s'", registry.db_filename);
+
+        // move the .tmp to make it active
+        netdata_log_debug(D_REGISTRY, "REGISTRY: linking tmp db '%s' to active db '%s'", tmp_filename, registry.db_filename);
+        if (link(tmp_filename, registry.db_filename) == -1) {
+            netdata_log_error("REGISTRY: cannot move file '%s' to '%s'. Saving registry DB failed!", tmp_filename,
+                    registry.db_filename);
+
+            // move the .old back
+            netdata_log_debug(D_REGISTRY, "REGISTRY: linking old db '%s' to active db '%s'", old_filename, registry.db_filename);
+            if(link(old_filename, registry.db_filename) == -1)
+                netdata_log_error("REGISTRY: cannot move file '%s' to '%s'. Recovering the old registry DB failed!", old_filename, registry.db_filename);
+        }
+        else {
+            netdata_log_debug(D_REGISTRY, "REGISTRY: removing tmp db '%s'", tmp_filename);
+            if(unlink(tmp_filename) == -1)
+                netdata_log_error("REGISTRY: cannot remove tmp registry file '%s'", tmp_filename);
+
+            // it has been moved successfully
+            // discard the current registry log
+            registry_log_recreate();
+            registry.log_count = 0;
+        }
+    }
+
+    // continue operations
+    nd_log_limits_reset();
+
+    return -1;
+}
+
+// ----------------------------------------------------------------------------
+// LOAD THE REGISTRY DATABASE
+
+size_t registry_db_load(void) {
+    char *s, buf[4096 + 1];
+    REGISTRY_PERSON *p = NULL;
+    REGISTRY_MACHINE *m = NULL;
+    STRING *u = NULL;
+    size_t line = 0;
+
+    netdata_log_debug(D_REGISTRY, "REGISTRY: loading active db from: '%s'", registry.db_filename);
+    FILE *fp = fopen(registry.db_filename, "r");
+    if(!fp) {
+        if (errno != ENOENT)
+            netdata_log_error("REGISTRY: cannot open registry file: '%s'", registry.db_filename);
+        return 0;
+    }
+
+    REGISTRY_MACHINE_URL *mu;
+    size_t len = 0;
+    buf[4096] = '\0';
+    while((s = fgets_trim_len(buf, 4096, fp, &len))) {
+        line++;
+
+        netdata_log_debug(D_REGISTRY, "REGISTRY: read line %zu to length %zu: %s", line, len, s);
+        switch(*s) {
+            case 'U': // person URL
+                if(unlikely(!p)) {
+                    netdata_log_error("REGISTRY: ignoring line %zu, no person loaded: %s", line, s);
+                    continue;
+                }
+
+                // verify it is valid
+                if(len < 69 || s[1] != '\t' || s[10] != '\t' || s[19] != '\t' || s[28] != '\t' || s[31] != '\t' || s[68] != '\t') {
+                    netdata_log_error("REGISTRY: person URL line %zu is wrong (len = %zu).", line, len);
+                    continue;
+                }
+
+                s[1] = s[10] = s[19] = s[28] = s[31] = s[68] = '\0';
+
+                // skip the name to find the url
+                char *url = &s[69];
+                while(*url && *url != '\t') url++;
+                if(!*url) {
+                    netdata_log_error("REGISTRY: person URL line %zu does not have a url.", line);
+                    continue;
+                }
+                *url++ = '\0';
+
+                if(*url != 'h' && *url != '*') {
+                    netdata_log_error("REGISTRY: person URL line %zu does not have a valid url: %s", line, url);
+                    continue;
+                }
+
+                u = string_strdupz(url);
+
+                time_t first_t = (time_t)strtoul(&s[2], NULL, 16);
+
+                m = registry_machine_find(&s[32]);
+                if(!m) m = registry_machine_allocate(&s[32], first_t);
+
+                mu = registry_machine_url_find(m, u);
+                if(!mu) {
+                    netdata_log_error("REGISTRY: person URL line %zu was not linked to the machine it refers to", line);
+                    mu = registry_machine_url_allocate(m, u, first_t);
+                }
+
+                REGISTRY_PERSON_URL *pu = registry_person_url_index_find(p, u);
+                if(!pu)
+                    pu = registry_person_url_allocate(p, m, u, &s[69], strlen(&s[69]), first_t);
+                else
+                    netdata_log_error("REGISTRY: person URL line %zu is duplicate, reusing the old one.", line);
+
+                pu->last_t = (uint32_t)strtoul(&s[11], NULL, 16);
+                pu->usages = (uint32_t)strtoul(&s[20], NULL, 16);
+                pu->flags = (uint8_t)strtoul(&s[29], NULL, 16);
+                netdata_log_debug(D_REGISTRY, "REGISTRY: loaded person URL '%s' with name '%s' of machine '%s', first: %u, last: %u, usages: %u, flags: %02x",
+                      string2str(u), string2str(pu->machine_name), m->guid, pu->first_t, pu->last_t, pu->usages, pu->flags);
+
+                string_freez(u);
+                break;
+
+            case 'P': // person
+                m = NULL;
+                // verify it is valid
+                if(unlikely(len != 65 || s[1] != '\t' || s[10] != '\t' || s[19] != '\t' || s[28] != '\t' || s[65] != '\0')) {
+                    netdata_log_error("REGISTRY: person line %zu is wrong (len = %zu).", line, len);
+                    continue;
+                }
+
+                s[1] = s[10] = s[19] = s[28] = '\0';
+                p = registry_person_allocate(&s[29], (time_t)strtoul(&s[2], NULL, 16));
+                p->last_t = (uint32_t)strtoul(&s[11], NULL, 16);
+                p->usages = (uint32_t)strtoul(&s[20], NULL, 16);
+                netdata_log_debug(D_REGISTRY, "REGISTRY: loaded person '%s', first: %u, last: %u, usages: %u", p->guid, p->first_t, p->last_t, p->usages);
+                break;
+
+            case 'V': // machine URL
+                if(unlikely(!m)) {
+                    netdata_log_error("REGISTRY: ignoring line %zu, no machine loaded: %s", line, s);
+                    continue;
+                }
+
+                // verify it is valid
+                if(len < 32 || s[1] != '\t' || s[10] != '\t' || s[19] != '\t' || s[28] != '\t' || s[31] != '\t') {
+                    netdata_log_error("REGISTRY: person URL line %zu is wrong (len = %zu).", line, len);
+                    continue;
+                }
+
+                s[1] = s[10] = s[19] = s[28] = s[31] = '\0';
+
+                url = &s[32];
+                if(*url != 'h' && *url != '*') {
+                    netdata_log_error("REGISTRY: machine URL line %zu does not have a valid url: %s", line, url);
+                    continue;
+                }
+
+                u = string_strdupz(url);
+
+                mu = registry_machine_url_find(m, u);
+                if(!mu)
+                    mu = registry_machine_url_allocate(m, u, (time_t)strtoul(&s[2], NULL, 16));
+                else
+                    netdata_log_error("REGISTRY: machine URL line %zu is duplicate, reusing the old one.", line);
+
+                mu->last_t = (uint32_t)strtoul(&s[11], NULL, 16);
+                mu->usages = (uint32_t)strtoul(&s[20], NULL, 16);
+                mu->flags = (uint8_t)strtoul(&s[29], NULL, 16);
+                netdata_log_debug(D_REGISTRY, "Registry loaded machine URL '%s', machine '%s', first: %u, last: %u, usages: %u, flags: %02x",
+                      string2str(u), m->guid, mu->first_t, mu->last_t, mu->usages, mu->flags);
+
+                string_freez(u);
+                break;
+
+            case 'M': // machine
+                p = NULL;
+                // verify it is valid
+                if(unlikely(len != 65 || s[1] != '\t' || s[10] != '\t' || s[19] != '\t' || s[28] != '\t' || s[65] != '\0')) {
+                    netdata_log_error("REGISTRY: person line %zu is wrong (len = %zu).", line, len);
+                    continue;
+                }
+
+                s[1] = s[10] = s[19] = s[28] = '\0';
+                m = registry_machine_allocate(&s[29], (time_t)strtoul(&s[2], NULL, 16));
+                m->last_t = (uint32_t)strtoul(&s[11], NULL, 16);
+                m->usages = (uint32_t)strtoul(&s[20], NULL, 16);
+                netdata_log_debug(D_REGISTRY, "REGISTRY: loaded machine '%s', first: %u, last: %u, usages: %u", m->guid, m->first_t, m->last_t, m->usages);
+                break;
+
+            case 'T': // totals
+                if(unlikely(len != 103 || s[1] != '\t' || s[18] != '\t' || s[35] != '\t' || s[52] != '\t' || s[69] != '\t' || s[86] != '\t' || s[103] != '\0')) {
+                    netdata_log_error("REGISTRY: totals line %zu is wrong (len = %zu).", line, len);
+                    continue;
+                }
+                registry.persons_count = strtoull(&s[2], NULL, 16);
+                registry.machines_count = strtoull(&s[19], NULL, 16);
+                registry.usages_count = strtoull(&s[36], NULL, 16);
+                registry.persons_urls_count = strtoull(&s[70], NULL, 16);
+                registry.machines_urls_count = strtoull(&s[87], NULL, 16);
+                break;
+
+            default:
+                netdata_log_error("REGISTRY: ignoring line %zu of filename '%s': %s.", line, registry.db_filename, s);
+                break;
+        }
+    }
+    fclose(fp);
+
+    return line;
+}
diff --git a/registry/registry_init.c b/registry/registry_init.c
new file mode 100644
index 00000000..79523e25
--- /dev/null
+++ b/registry/registry_init.c
@@ -0,0 +1,249 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+#include "daemon/common.h"
+#include "registry_internals.h"
+
+void registry_db_stats(void) {
+    size_t persons = 0;
+    size_t persons_urls = 0;
+    size_t max_urls_per_person = 0;
+
+    REGISTRY_PERSON *p;
+    dfe_start_read(registry.persons, p) {
+        persons++;
+        size_t urls = 0;
+        for(REGISTRY_PERSON_URL *pu = p->person_urls ; pu ;pu = pu->next)
+            urls++;
+
+        if(urls > max_urls_per_person)
+            max_urls_per_person = urls;
+
+        persons_urls += urls;
+    }
+    dfe_done(p);
+
+    size_t machines = 0;
+    size_t machines_urls = 0;
+    size_t max_urls_per_machine = 0;
+
+    REGISTRY_MACHINE *m;
+    dfe_start_read(registry.machines, m) {
+                machines++;
+                size_t urls = 0;
+                for(REGISTRY_MACHINE_URL *mu = m->machine_urls ; mu ;mu = mu->next)
+                    urls++;
+
+                if(urls > max_urls_per_machine)
+                    max_urls_per_machine = urls;
+
+                machines_urls += urls;
+            }
+    dfe_done(m);
+
+    netdata_log_info("REGISTRY: persons %zu, person_urls %zu, max_urls_per_person %zu, "
+                     "machines %zu, machine_urls %zu, max_urls_per_machine %zu",
+                     persons, persons_urls, max_urls_per_person,
+                     machines, machines_urls, max_urls_per_machine);
+}
+
+void registry_generate_curl_urls(void) {
+    FILE *fp = fopen("/tmp/registry.curl", "w+");
+    if (unlikely(!fp))
+        return;
+
+    REGISTRY_PERSON *p;
+    dfe_start_read(registry.persons, p) {
+        for(REGISTRY_PERSON_URL *pu = p->person_urls ; pu ;pu = pu->next) {
+            fprintf(fp, "do_curl '%s' '%s' '%s'\n", p->guid, pu->machine->guid, string2str(pu->url));
+        }
+    }
+    dfe_done(p);
+
+    fclose(fp);
+}
+
+int registry_init(void) {
+    char filename[FILENAME_MAX + 1];
+
+    // registry enabled?
+    if(web_server_mode != WEB_SERVER_MODE_NONE) {
+        registry.enabled = config_get_boolean(CONFIG_SECTION_REGISTRY, "enabled", 0);
+    }
+    else {
+        netdata_log_info("Registry is disabled - use the central netdata");
+        config_set_boolean(CONFIG_SECTION_REGISTRY, "enabled", 0);
+        registry.enabled = 0;
+    }
+
+    // path names
+    snprintfz(filename, FILENAME_MAX, "%s/registry", netdata_configured_varlib_dir);
+    registry.pathname = config_get(CONFIG_SECTION_DIRECTORIES, "registry", filename);
+    if(mkdir(registry.pathname, 0770) == -1 && errno != EEXIST)
+        fatal("Cannot create directory '%s'.", registry.pathname);
+
+    // filenames
+    snprintfz(filename, FILENAME_MAX, "%s/netdata.public.unique.id", registry.pathname);
+    registry.machine_guid_filename = config_get(CONFIG_SECTION_REGISTRY, "netdata unique id file", filename);
+
+    snprintfz(filename, FILENAME_MAX, "%s/registry.db", registry.pathname);
+    registry.db_filename = config_get(CONFIG_SECTION_REGISTRY, "registry db file", filename);
+
+    snprintfz(filename, FILENAME_MAX, "%s/registry-log.db", registry.pathname);
+    registry.log_filename = config_get(CONFIG_SECTION_REGISTRY, "registry log file", filename);
+
+    // configuration options
+    registry.save_registry_every_entries = (unsigned long long)config_get_number(CONFIG_SECTION_REGISTRY, "registry save db every new entries", 1000000);
+    registry.persons_expiration = config_get_number(CONFIG_SECTION_REGISTRY, "registry expire idle persons days", 365) * 86400;
+    registry.registry_domain = config_get(CONFIG_SECTION_REGISTRY, "registry domain", "");
+    registry.registry_to_announce = config_get(CONFIG_SECTION_REGISTRY, "registry to announce", "https://registry.my-netdata.io");
+    registry.hostname = config_get(CONFIG_SECTION_REGISTRY, "registry hostname", netdata_configured_hostname);
+    registry.verify_cookies_redirects = config_get_boolean(CONFIG_SECTION_REGISTRY, "verify browser cookies support", 1);
+    registry.enable_cookies_samesite_secure = config_get_boolean(CONFIG_SECTION_REGISTRY, "enable cookies SameSite and Secure", 1);
+
+    registry_update_cloud_base_url();
+    setenv("NETDATA_REGISTRY_HOSTNAME", registry.hostname, 1);
+    setenv("NETDATA_REGISTRY_URL", registry.registry_to_announce, 1);
+
+    registry.max_url_length = (size_t)config_get_number(CONFIG_SECTION_REGISTRY, "max URL length", 1024);
+    if(registry.max_url_length < 10) {
+        registry.max_url_length = 10;
+        config_set_number(CONFIG_SECTION_REGISTRY, "max URL length", (long long)registry.max_url_length);
+    }
+
+    registry.max_name_length = (size_t)config_get_number(CONFIG_SECTION_REGISTRY, "max URL name length", 50);
+    if(registry.max_name_length < 10) {
+        registry.max_name_length = 10;
+        config_set_number(CONFIG_SECTION_REGISTRY, "max URL name length", (long long)registry.max_name_length);
+    }
+
+    bool use_mmap = config_get_boolean(CONFIG_SECTION_REGISTRY, "use mmap", false);
+
+    // initialize entries counters
+    registry.persons_count = 0;
+    registry.machines_count = 0;
+    registry.usages_count = 0;
+    registry.persons_urls_count = 0;
+    registry.machines_urls_count = 0;
+
+    // initialize locks
+    netdata_mutex_init(&registry.lock);
+
+    // load the registry database
+    if(registry.enabled) {
+        // create dictionaries
+        registry.persons = dictionary_create(REGISTRY_DICTIONARY_OPTIONS);
+        registry.machines = dictionary_create(REGISTRY_DICTIONARY_OPTIONS);
+
+        // initialize the allocators
+
+        size_t min_page_size = 4 * 1024;
+        size_t max_page_size = 1024 * 1024;
+
+        if(use_mmap) {
+            min_page_size = 100 * 1024 * 1024;
+            max_page_size = 512 * 1024 * 1024;
+        }
+
+        registry.persons_aral = aral_create("registry_persons", sizeof(REGISTRY_PERSON),
+                                            min_page_size / sizeof(REGISTRY_PERSON), max_page_size,
+                                            &registry.aral_stats,
+                                            "registry_persons",
+                                            &netdata_configured_cache_dir,
+                                            use_mmap, true);
+
+        registry.machines_aral = aral_create("registry_machines", sizeof(REGISTRY_MACHINE),
+                                             min_page_size / sizeof(REGISTRY_MACHINE), max_page_size,
+                                             &registry.aral_stats,
+                                             "registry_machines",
+                                             &netdata_configured_cache_dir,
+                                             use_mmap, true);
+
+        registry.person_urls_aral = aral_create("registry_person_urls", sizeof(REGISTRY_PERSON_URL),
+                                                min_page_size / sizeof(REGISTRY_PERSON_URL), max_page_size,
+                                                &registry.aral_stats,
+                                                "registry_person_urls",
+                                                &netdata_configured_cache_dir,
+                                                use_mmap, true);
+
+        registry.machine_urls_aral = aral_create("registry_machine_urls", sizeof(REGISTRY_MACHINE_URL),
+                                                 min_page_size / sizeof(REGISTRY_MACHINE_URL), max_page_size,
+                                                 &registry.aral_stats,
+                                                 "registry_machine_urls",
+                                                 &netdata_configured_cache_dir,
+                                                 use_mmap, true);
+
+        // disable cancelability to avoid enable/disable per item in the dictionary locks
+        netdata_thread_disable_cancelability();
+
+        registry_log_open();
+        registry_db_load();
+        registry_log_load();
+
+        if(unlikely(registry_db_should_be_saved()))
+            registry_db_save();
+
+//        registry_db_stats();
+//        registry_generate_curl_urls();
+//        exit(0);
+
+        netdata_thread_enable_cancelability();
+    }
+
+    return 0;
+}
+
+static int machine_delete_callback(const DICTIONARY_ITEM *item __maybe_unused, void *entry, void *data __maybe_unused) {
+    REGISTRY_MACHINE *m = (REGISTRY_MACHINE *)entry;
+
+    int count = 0;
+
+    while(m->machine_urls) {
+        registry_machine_url_unlink_from_machine_and_free(m, m->machine_urls);
+        count++;
+    }
+
+    aral_freez(registry.machines_aral, m);
+
+    return count + 1;
+}
+
+static int registry_person_del_callback(const DICTIONARY_ITEM *item __maybe_unused, void *entry, void *d __maybe_unused) {
+    REGISTRY_PERSON *p = (REGISTRY_PERSON *)entry;
+
+    netdata_log_debug(D_REGISTRY, "Registry: registry_person_del('%s'): deleting person", p->guid);
+
+    while(p->person_urls)
+        registry_person_unlink_from_url(p, (REGISTRY_PERSON_URL *)p->person_urls);
+
+    //debug(D_REGISTRY, "Registry: deleting person '%s' from persons registry", p->guid);
+    //dictionary_del(registry.persons, p->guid);
+
+    netdata_log_debug(D_REGISTRY, "Registry: freeing person '%s'", p->guid);
+    aral_freez(registry.persons_aral, p);
+
+    return 1;
+}
+
+void registry_free(void) {
+    if(!registry.enabled) return;
+    registry.enabled = false;
+
+    netdata_log_debug(D_REGISTRY, "Registry: destroying persons dictionary");
+    dictionary_walkthrough_read(registry.persons, registry_person_del_callback, NULL);
+    dictionary_destroy(registry.persons);
+    registry.persons = NULL;
+
+    netdata_log_debug(D_REGISTRY, "Registry: destroying machines dictionary");
+    dictionary_walkthrough_read(registry.machines, machine_delete_callback, NULL);
+    dictionary_destroy(registry.machines);
+    registry.machines = NULL;
+
+    aral_destroy(registry.persons_aral);
+    aral_destroy(registry.machines_aral);
+    aral_destroy(registry.person_urls_aral);
+    aral_destroy(registry.machine_urls_aral);
+    registry.persons_aral = NULL;
+    registry.machines_aral = NULL;
+    registry.person_urls_aral = NULL;
+    registry.machine_urls_aral = NULL;
+}
diff --git a/registry/registry_internals.c b/registry/registry_internals.c
new file mode 100644
index 00000000..74f12b55
--- /dev/null
+++ b/registry/registry_internals.c
@@ -0,0 +1,321 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+#include "daemon/common.h"
+#include "registry_internals.h"
+
+struct registry registry;
+
+// ----------------------------------------------------------------------------
+// common functions
+
+// parse a GUID and re-generated to be always lower case
+// this is used as a protection against the variations of GUIDs
+int regenerate_guid(const char *guid, char *result) {
+    uuid_t uuid;
+    if(unlikely(uuid_parse(guid, uuid) == -1)) {
+        netdata_log_info("Registry: GUID '%s' is not a valid GUID.", guid);
+        return -1;
+    }
+    else {
+        uuid_unparse_lower(uuid, result);
+
+#ifdef NETDATA_INTERNAL_CHECKS
+        if(strcmp(guid, result) != 0)
+            netdata_log_info("GUID '%s' and re-generated GUID '%s' differ!", guid, result);
+#endif /* NETDATA_INTERNAL_CHECKS */
+    }
+
+    return 0;
+}
+
+// make sure the names of the machines / URLs do not contain any tabs
+// (which are used as our separator in the database files)
+// and are properly trimmed (before and after)
+static inline char *registry_fix_machine_name(char *name, size_t *len) {
+    char *s = name?name:"";
+
+    // skip leading spaces
+    while(*s && isspace(*s)) s++;
+
+    // make sure all spaces are a SPACE
+    char *t = s;
+    while(*t) {
+        if(unlikely(isspace(*t)))
+            *t = ' ';
+
+        t++;
+    }
+
+    // remove trailing spaces
+    while(--t >= s) {
+        if(*t == ' ')
+            *t = '\0';
+        else
+            break;
+    }
+    t++;
+
+    if(likely(len))
+        *len = (t - s);
+
+    return s;
+}
+
+static inline char *registry_fix_url(char *url, size_t *len) {
+    size_t l = 0;
+    char *s = registry_fix_machine_name(url, &l);
+
+    // protection from too big URLs
+    if(l > registry.max_url_length) {
+        l = registry.max_url_length;
+        s[l] = '\0';
+    }
+
+    if(len) *len = l;
+    return s;
+}
+
+
+// ----------------------------------------------------------------------------
+// HELPERS
+
+// verify the person, the machine and the URL exist in our DB
+REGISTRY_PERSON_URL *registry_verify_request(const char *person_guid, char *machine_guid, char *url, REGISTRY_PERSON **pp, REGISTRY_MACHINE **mm) {
+    char pbuf[GUID_LEN + 1], mbuf[GUID_LEN + 1];
+
+    if(!person_guid || !*person_guid || !machine_guid || !*machine_guid || !url || !*url) {
+        netdata_log_info("Registry Request Verification: invalid request! person: '%s', machine '%s', url '%s'", person_guid?person_guid:"UNSET", machine_guid?machine_guid:"UNSET", url?url:"UNSET");
+        return NULL;
+    }
+
+    // normalize the url
+    url = registry_fix_url(url, NULL);
+
+    // make sure the person GUID is valid
+    if(regenerate_guid(person_guid, pbuf) == -1) {
+        netdata_log_info("Registry Request Verification: invalid person GUID, person: '%s', machine '%s', url '%s'", person_guid, machine_guid, url);
+        return NULL;
+    }
+    person_guid = pbuf;
+
+    // make sure the machine GUID is valid
+    if(regenerate_guid(machine_guid, mbuf) == -1) {
+        netdata_log_info("Registry Request Verification: invalid machine GUID, person: '%s', machine '%s', url '%s'", person_guid, machine_guid, url);
+        return NULL;
+    }
+    machine_guid = mbuf;
+
+    // make sure the machine exists
+    REGISTRY_MACHINE *m = registry_machine_find(machine_guid);
+    if(!m) {
+        netdata_log_info("Registry Request Verification: machine not found, person: '%s', machine '%s', url '%s'", person_guid, machine_guid, url);
+        return NULL;
+    }
+    if(mm) *mm = m;
+
+    // make sure the person exist
+    REGISTRY_PERSON *p = registry_person_find(person_guid);
+    if(!p) {
+        netdata_log_info("Registry Request Verification: person not found, person: '%s', machine '%s', url '%s'", person_guid, machine_guid, url);
+        return NULL;
+    }
+    if(pp) *pp = p;
+
+    STRING *u = string_strdupz(url);
+    REGISTRY_PERSON_URL *pu = registry_person_url_index_find(p, u);
+    string_freez(u);
+
+    if(!pu) {
+        netdata_log_info("Registry Request Verification: URL not found for person, person: '%s', machine '%s', url '%s'", person_guid, machine_guid, url);
+        return NULL;
+    }
+    //else if (pu->machine != m) {
+    //    netdata_log_info("Registry Request Verification: Machine mismatch: person: '%s', machine requested='%s' <> loaded='%s', url '%s'", person_guid, machine_guid, pu->machine->guid, url);
+    //    return NULL;
+    //}
+
+    return pu;
+}
+
+
+// ----------------------------------------------------------------------------
+// REGISTRY REQUESTS
+
+REGISTRY_PERSON *registry_request_access(const char *person_guid, char *machine_guid, char *url, char *name, time_t when) {
+    netdata_log_debug(D_REGISTRY, "registry_request_access('%s', '%s', '%s'): NEW REQUEST", (person_guid)?person_guid:"", machine_guid, url);
+
+    bool is_dummy = is_dummy_person(person_guid);
+
+    REGISTRY_MACHINE *m = registry_machine_find_or_create(machine_guid, when, is_dummy);
+    if(!m) return NULL;
+
+    REGISTRY_PERSON *p = registry_person_find_or_create(person_guid, when, is_dummy);
+
+    // make sure the name is valid
+    size_t name_len;
+    name = registry_fix_machine_name(name, &name_len);
+
+    size_t url_len;
+    url = registry_fix_url(url, &url_len);
+
+    STRING *u = string_strdupz(url);
+
+    if(!is_dummy)
+        registry_person_link_to_url(p, m, u, name, name_len, when);
+
+    registry_machine_link_to_url(m, u, when);
+
+    registry_log('A', p, m, u, name);
+
+    registry.usages_count++;
+
+    return p;
+}
+
+REGISTRY_PERSON *registry_request_delete(const char *person_guid, char *machine_guid, char *url, char *delete_url, time_t when) {
+    (void) when;
+
+    REGISTRY_PERSON *p = NULL;
+    REGISTRY_MACHINE *m = NULL;
+    REGISTRY_PERSON_URL *pu = registry_verify_request(person_guid, machine_guid, url, &p, &m);
+    if(!pu || !p || !m) return NULL;
+
+    // normalize the url
+    delete_url = registry_fix_url(delete_url, NULL);
+
+    // make sure the user is not deleting the url it uses
+    /*
+    if(!strcmp(delete_url, pu->url->url)) {
+        netdata_log_info("Registry Delete Request: delete URL is the one currently accessed, person: '%s', machine '%s', url '%s', delete url '%s'"
+             , p->guid, m->guid, pu->url->url, delete_url);
+        return NULL;
+    }
+    */
+
+    STRING *d_url = string_strdupz(delete_url);
+    REGISTRY_PERSON_URL *dpu = registry_person_url_index_find(p, d_url);
+    string_freez(d_url);
+
+    if(!dpu) {
+        netdata_log_info("Registry Delete Request: URL not found for person: '%s', machine '%s', url '%s', delete url '%s'", p->guid
+             , m->guid, string2str(pu->url), delete_url);
+        return NULL;
+    }
+
+    registry_log('D', p, m, pu->url, string2str(dpu->url));
+    registry_person_unlink_from_url(p, dpu);
+
+    return p;
+}
+
+
+REGISTRY_MACHINE *registry_request_machine(const char *person_guid, char *request_machine, STRING **hostname) {
+    char pbuf[GUID_LEN + 1];
+    char mbuf[GUID_LEN + 1];
+
+    // make sure the person GUID is valid
+    if(regenerate_guid(person_guid, pbuf) == -1) {
+        netdata_log_info("REGISTRY: %s(): invalid person GUID '%s'", __FUNCTION__ , person_guid);
+        return NULL;
+    }
+    person_guid = pbuf;
+
+    // make sure the person GUID is valid
+    if(regenerate_guid(request_machine, mbuf) == -1) {
+        netdata_log_info("REGISTRY: %s(): invalid search machine GUID '%s'", __FUNCTION__ , request_machine);
+        return NULL;
+    }
+    request_machine = mbuf;
+
+    REGISTRY_PERSON *p = registry_person_find(person_guid);
+    if(!p) return NULL;
+
+    REGISTRY_MACHINE *m = registry_machine_find(request_machine);
+    if(!m) return NULL;
+
+    // Verify the user has in the past accessed this machine
+    // We will walk through the PERSON_URLs to find the machine
+    // linking to our machine
+
+    // make sure the user has access
+    for(REGISTRY_PERSON_URL *pu = p->person_urls; pu ;pu = pu->next)
+        if(pu->machine == m) {
+            *hostname = string_dup(pu->machine_name);
+            return m;
+        }
+
+    return NULL;
+}
+
+
+// ----------------------------------------------------------------------------
+// REGISTRY THIS MACHINE UNIQUE ID
+
+static inline int is_machine_guid_blacklisted(const char *guid) {
+    // these are machine GUIDs that have been included in distribution packages.
+    // we blacklist them here, so that the next version of netdata will generate
+    // new ones.
+
+    if(!strcmp(guid, "8a795b0c-2311-11e6-8563-000c295076a6")
+       || !strcmp(guid, "4aed1458-1c3e-11e6-a53f-000c290fc8f5")
+            ) {
+        netdata_log_error("Blacklisted machine GUID '%s' found.", guid);
+        return 1;
+    }
+
+    return 0;
+}
+
+char *registry_get_this_machine_hostname(void) {
+    return registry.hostname;
+}
+
+char *registry_get_this_machine_guid(void) {
+    static char guid[GUID_LEN + 1] = "";
+
+    if(likely(guid[0]))
+        return guid;
+
+    // read it from disk
+    int fd = open(registry.machine_guid_filename, O_RDONLY);
+    if(fd != -1) {
+        char buf[GUID_LEN + 1];
+        if(read(fd, buf, GUID_LEN) != GUID_LEN)
+            netdata_log_error("Failed to read machine GUID from '%s'", registry.machine_guid_filename);
+        else {
+            buf[GUID_LEN] = '\0';
+            if(regenerate_guid(buf, guid) == -1) {
+                netdata_log_error("Failed to validate machine GUID '%s' from '%s'. Ignoring it - this might mean this netdata will appear as duplicate in the registry.",
+                        buf, registry.machine_guid_filename);
+
+                guid[0] = '\0';
+            }
+            else if(is_machine_guid_blacklisted(guid))
+                guid[0] = '\0';
+        }
+        close(fd);
+    }
+
+    // generate a new one?
+    if(!guid[0]) {
+        uuid_t uuid;
+
+        uuid_generate_time(uuid);
+        uuid_unparse_lower(uuid, guid);
+        guid[GUID_LEN] = '\0';
+
+        // save it
+        fd = open(registry.machine_guid_filename, O_WRONLY|O_CREAT|O_TRUNC, 444);
+        if(fd == -1)
+            fatal("Cannot create unique machine id file '%s'. Please fix this.", registry.machine_guid_filename);
+
+        if(write(fd, guid, GUID_LEN) != GUID_LEN)
+            fatal("Cannot write the unique machine id file '%s'. Please fix this.", registry.machine_guid_filename);
+
+        close(fd);
+    }
+
+    setenv("NETDATA_REGISTRY_UNIQUE_ID", guid, 1);
+
+    return guid;
+}
diff --git a/registry/registry_internals.h b/registry/registry_internals.h
new file mode 100644
index 00000000..c7f8f43d
--- /dev/null
+++ b/registry/registry_internals.h
@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+#ifndef NETDATA_REGISTRY_INTERNALS_H_H
+#define NETDATA_REGISTRY_INTERNALS_H_H 1
+
+#include "registry.h"
+
+#define REGISTRY_URL_FLAGS_DEFAULT 0x00
+#define REGISTRY_URL_FLAGS_EXPIRED 0x01
+
+#define REGISTRY_DICTIONARY_OPTIONS (DICT_OPTION_VALUE_LINK_DONT_CLONE | DICT_OPTION_NAME_LINK_DONT_CLONE | DICT_OPTION_SINGLE_THREADED)
+
+#define REGISTRY_VERIFY_COOKIES_GUID "11111111-2222-3333-4444-555555555555"
+#define is_dummy_person(person_guid) (strcmp(person_guid, REGISTRY_VERIFY_COOKIES_GUID) == 0)
+
+// ----------------------------------------------------------------------------
+// COMMON structures
+
+struct registry {
+    int enabled;
+    netdata_mutex_t lock;
+
+    // entries counters / statistics
+    unsigned long long persons_count;
+    unsigned long long machines_count;
+    unsigned long long usages_count;
+    unsigned long long persons_urls_count;
+    unsigned long long machines_urls_count;
+    unsigned long long log_count;
+
+    // configuration
+    unsigned long long save_registry_every_entries;
+    char *registry_domain;
+    char *hostname;
+    char *registry_to_announce;
+    char *cloud_base_url;
+    time_t persons_expiration; // seconds to expire idle persons
+    int verify_cookies_redirects;
+    int enable_cookies_samesite_secure;
+
+    size_t max_url_length;
+    size_t max_name_length;
+
+    // file/path names
+    char *pathname;
+    char *db_filename;
+    char *log_filename;
+    char *machine_guid_filename;
+
+    // open files
+    FILE *log_fp;
+
+    // the database
+    DICTIONARY *persons;    // dictionary of REGISTRY_PERSON *,  with key the REGISTRY_PERSON.guid
+    DICTIONARY *machines;   // dictionary of REGISTRY_MACHINE *, with key the REGISTRY_MACHINE.guid
+
+    ARAL *persons_aral;
+    ARAL *machines_aral;
+
+    ARAL *person_urls_aral;
+    ARAL *machine_urls_aral;
+
+    struct aral_statistics aral_stats;
+};
+
+#include "registry_machine.h"
+#include "registry_person.h"
+#include "registry.h"
+
+extern struct registry registry;
+
+// REGISTRY LOW-LEVEL REQUESTS (in registry-internals.c)
+REGISTRY_PERSON *registry_request_access(const char *person_guid, char *machine_guid, char *url, char *name, time_t when);
+REGISTRY_PERSON *registry_request_delete(const char *person_guid, char *machine_guid, char *url, char *delete_url, time_t when);
+REGISTRY_MACHINE *registry_request_machine(const char *person_guid, char *request_machine, STRING **hostname);
+
+// REGISTRY LOG (in registry_log.c)
+void registry_log(char action, REGISTRY_PERSON *p, REGISTRY_MACHINE *m, STRING *u, const char *name);
+int registry_log_open(void);
+void registry_log_close(void);
+void registry_log_recreate(void);
+ssize_t registry_log_load(void);
+
+// REGISTRY DB (in registry_db.c)
+int registry_db_save(void);
+size_t registry_db_load(void);
+int registry_db_should_be_saved(void);
+
+#endif //NETDATA_REGISTRY_INTERNALS_H_H
diff --git a/registry/registry_log.c b/registry/registry_log.c
new file mode 100644
index 00000000..118d47c1
--- /dev/null
+++ b/registry/registry_log.c
@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+#include "daemon/common.h"
+#include "registry_internals.h"
+
+void registry_log(char action, REGISTRY_PERSON *p, REGISTRY_MACHINE *m, STRING *u, const char *name) {
+    if(likely(registry.log_fp)) {
+        if(unlikely(fprintf(registry.log_fp, "%c\t%08x\t%s\t%s\t%s\t%s\n",
+                action,
+                p->last_t,
+                p->guid,
+                m->guid,
+                name,
+                string2str(u)) < 0))
+            netdata_log_error("Registry: failed to save log. Registry data may be lost in case of abnormal restart.");
+
+        // we increase the counter even on failures
+        // so that the registry will be saved periodically
+        registry.log_count++;
+
+        // this must be outside the log_lock(), or a deadlock will happen.
+        // registry_db_save() checks the same inside the log_lock, so only
+        // one thread will save the db
+        if(unlikely(registry_db_should_be_saved()))
+            registry_db_save();
+    }
+}
+
+int registry_log_open(void) {
+    if(registry.log_fp)
+        fclose(registry.log_fp);
+
+    registry.log_fp = fopen(registry.log_filename, "a");
+    if(registry.log_fp) {
+        if (setvbuf(registry.log_fp, NULL, _IOLBF, 0) != 0)
+            netdata_log_error("Cannot set line buffering on registry log file.");
+        return 0;
+    }
+
+    netdata_log_error("Cannot open registry log file '%s'. Registry data will be lost in case of netdata or server crash.", registry.log_filename);
+    return -1;
+}
+
+void registry_log_close(void) {
+    if(registry.log_fp) {
+        fclose(registry.log_fp);
+        registry.log_fp = NULL;
+    }
+}
+
+void registry_log_recreate(void) {
+    if(registry.log_fp != NULL) {
+        registry_log_close();
+
+        // open it with truncate
+        registry.log_fp = fopen(registry.log_filename, "w");
+        if(registry.log_fp) fclose(registry.log_fp);
+        else
+            netdata_log_error("Cannot truncate registry log '%s'", registry.log_filename);
+
+        registry.log_fp = NULL;
+        registry_log_open();
+    }
+}
+
+ssize_t registry_log_load(void) {
+    ssize_t line = -1;
+
+    // closing the log is required here
+    // otherwise we will append to it the values we read
+    registry_log_close();
+
+    netdata_log_debug(D_REGISTRY, "Registry: loading active db from: %s", registry.log_filename);
+    FILE *fp = fopen(registry.log_filename, "r");
+    if(!fp)
+        netdata_log_error("Registry: cannot open registry file: %s", registry.log_filename);
+    else {
+        char *s, buf[4096 + 1];
+        line = 0;
+        size_t len = 0;
+
+        while ((s = fgets_trim_len(buf, 4096, fp, &len))) {
+            line++;
+
+            switch (s[0]) {
+                case 'A': // accesses
+                case 'D': // deletes
+
+                    // verify it is valid
+                    if (unlikely(len < 85 || s[1] != '\t' || s[10] != '\t' || s[47] != '\t' || s[84] != '\t')) {
+                        netdata_log_error("Registry: log line %zd is wrong (len = %zu).", line, len);
+                        continue;
+                    }
+                    s[1] = s[10] = s[47] = s[84] = '\0';
+
+                    // get the variables
+                    time_t when = (time_t)strtoul(&s[2], NULL, 16);
+                    char *person_guid = &s[11];
+                    char *machine_guid = &s[48];
+                    char *name = &s[85];
+
+                    // skip the name to find the url
+                    char *url = name;
+                    while(*url && *url != '\t') url++;
+                    if(!*url) {
+                        netdata_log_error("Registry: log line %zd does not have a url.", line);
+                        continue;
+                    }
+                    *url++ = '\0';
+
+                    // make sure the person exists
+                    // without this, a new person guid will be created
+                    REGISTRY_PERSON *p = registry_person_find(person_guid);
+                    if(!p) p = registry_person_allocate(person_guid, when);
+
+                    if(s[0] == 'A')
+                        registry_request_access(p->guid, machine_guid, url, name, when);
+                    else
+                        registry_request_delete(p->guid, machine_guid, url, name, when);
+
+                    registry.log_count++;
+                    break;
+
+                default:
+                    netdata_log_error("Registry: ignoring line %zd of filename '%s': %s.", line, registry.log_filename, s);
+                    break;
+            }
+        }
+
+        fclose(fp);
+    }
+
+    // open the log again
+    registry_log_open();
+
+    return line;
+}
diff --git a/registry/registry_machine.c b/registry/registry_machine.c
new file mode 100644
index 00000000..a94fb8ea
--- /dev/null
+++ b/registry/registry_machine.c
@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+#include "daemon/common.h"
+#include "registry_internals.h"
+
+// ----------------------------------------------------------------------------
+// MACHINE
+
+REGISTRY_MACHINE *registry_machine_find(const char *machine_guid) {
+    netdata_log_debug(D_REGISTRY, "REGISTRY: registry_machine_find('%s')", machine_guid);
+    return dictionary_get(registry.machines, machine_guid);
+}
+
+REGISTRY_MACHINE_URL *registry_machine_url_find(REGISTRY_MACHINE *m, STRING *url) {
+    REGISTRY_MACHINE_URL *mu;
+
+    for(mu = m->machine_urls; mu ;mu = mu->next)
+        if(mu->url == url)
+            break;
+
+    return mu;
+}
+
+void registry_machine_url_unlink_from_machine_and_free(REGISTRY_MACHINE *m, REGISTRY_MACHINE_URL *mu) {
+    DOUBLE_LINKED_LIST_REMOVE_ITEM_UNSAFE(m->machine_urls, mu, prev, next);
+    string_freez(mu->url);
+    aral_freez(registry.machine_urls_aral, mu);
+}
+
+REGISTRY_MACHINE_URL *registry_machine_url_allocate(REGISTRY_MACHINE *m, STRING *u, time_t when) {
+    netdata_log_debug(D_REGISTRY, "REGISTRY: registry_machine_url_allocate('%s', '%s'): allocating %zu bytes", m->guid, string2str(u), sizeof(REGISTRY_MACHINE_URL));
+
+    REGISTRY_MACHINE_URL *mu = aral_mallocz(registry.machine_urls_aral);
+
+    mu->first_t = mu->last_t = (uint32_t)when;
+    mu->usages = 1;
+    mu->url = string_dup(u);
+    mu->flags = REGISTRY_URL_FLAGS_DEFAULT;
+
+    netdata_log_debug(D_REGISTRY, "REGISTRY: registry_machine_url_allocate('%s', '%s'): indexing URL in machine", m->guid, string2str(u));
+
+    DOUBLE_LINKED_LIST_PREPEND_ITEM_UNSAFE(m->machine_urls, mu, prev, next);
+
+    return mu;
+}
+
+REGISTRY_MACHINE *registry_machine_allocate(const char *machine_guid, time_t when) {
+    netdata_log_debug(D_REGISTRY, "REGISTRY: registry_machine_allocate('%s'): creating new machine, sizeof(MACHINE)=%zu", machine_guid, sizeof(REGISTRY_MACHINE));
+
+    REGISTRY_MACHINE *m = aral_mallocz(registry.machines_aral);
+
+    strncpyz(m->guid, machine_guid, GUID_LEN);
+
+    m->machine_urls = NULL;
+
+    m->first_t = m->last_t = (uint32_t)when;
+    m->usages = 0;
+    m->links = 0;
+
+    registry.machines_count++;
+
+    dictionary_set(registry.machines, m->guid, m, sizeof(REGISTRY_MACHINE));
+
+    return m;
+}
+
+// 1. validate machine GUID
+// 2. if it is valid, find it or create it and return it
+// 3. if it is not valid, return NULL
+REGISTRY_MACHINE *registry_machine_find_or_create(const char *machine_guid, time_t when, bool is_dummy __maybe_unused) {
+    REGISTRY_MACHINE *m = NULL;
+
+    if(likely(machine_guid && *machine_guid)) {
+        // validate it is a GUID
+        char buf[GUID_LEN + 1];
+        if(unlikely(regenerate_guid(machine_guid, buf) == -1))
+            netdata_log_info("REGISTRY: machine guid '%s' is not a valid guid. Ignoring it.", machine_guid);
+        else {
+            machine_guid = buf;
+            m = registry_machine_find(machine_guid);
+            if(!m) m = registry_machine_allocate(machine_guid, when);
+        }
+    }
+
+    return m;
+}
+
+
+// ----------------------------------------------------------------------------
+// LINKING OF OBJECTS
+
+REGISTRY_MACHINE_URL *registry_machine_link_to_url(REGISTRY_MACHINE *m, STRING *url, time_t when) {
+    netdata_log_debug(D_REGISTRY, "REGISTRY: registry_machine_link_to_url('%s', '%s'): searching for URL in machine", m->guid, string2str(url));
+
+    REGISTRY_MACHINE_URL *mu = registry_machine_url_find(m, url);
+    if(!mu) {
+        netdata_log_debug(D_REGISTRY, "REGISTRY: registry_machine_link_to_url('%s', '%s'): not found", m->guid, string2str(url));
+        mu = registry_machine_url_allocate(m, url, when);
+        registry.machines_urls_count++;
+    }
+    else {
+        netdata_log_debug(D_REGISTRY, "REGISTRY: registry_machine_link_to_url('%s', '%s'): found", m->guid, string2str(url));
+        mu->usages++;
+        if(likely(mu->last_t < (uint32_t)when)) mu->last_t = (uint32_t)when;
+    }
+
+    m->usages++;
+    if(likely(m->last_t < (uint32_t)when)) m->last_t = (uint32_t)when;
+
+    if(mu->flags & REGISTRY_URL_FLAGS_EXPIRED) {
+        netdata_log_debug(D_REGISTRY, "REGISTRY: registry_machine_link_to_url('%s', '%s'): accessing an expired URL.", m->guid, string2str(url));
+        mu->flags &= ~REGISTRY_URL_FLAGS_EXPIRED;
+    }
+
+    return mu;
+}
diff --git a/registry/registry_machine.h b/registry/registry_machine.h
new file mode 100644
index 00000000..4e8a407f
--- /dev/null
+++ b/registry/registry_machine.h
@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+#ifndef NETDATA_REGISTRY_MACHINE_H
+#define NETDATA_REGISTRY_MACHINE_H 1
+
+#include "registry_internals.h"
+
+// ----------------------------------------------------------------------------
+// MACHINE structures
+
+// For each MACHINE-URL pair we keep this
+struct registry_machine_url {
+    STRING *url;                // de-duplicated URL
+
+    uint8_t flags;
+
+    uint32_t first_t;           // the first time we saw this
+    uint32_t last_t;            // the last time we saw this
+    uint32_t usages;            // how many times this has been accessed
+
+    struct registry_machine_url *prev, *next;
+};
+typedef struct registry_machine_url REGISTRY_MACHINE_URL;
+
+// A machine
+struct registry_machine {
+    char guid[GUID_LEN + 1];    // the GUID
+
+    uint32_t links;             // the number of REGISTRY_PERSON_URL linked to this machine
+
+    REGISTRY_MACHINE_URL *machine_urls;   // MACHINE_URL *
+
+    uint32_t first_t;           // the first time we saw this
+    uint32_t last_t;            // the last time we saw this
+    uint32_t usages;            // how many times this has been accessed
+};
+typedef struct registry_machine REGISTRY_MACHINE;
+
+REGISTRY_MACHINE *registry_machine_find(const char *machine_guid);
+REGISTRY_MACHINE_URL *registry_machine_url_allocate(REGISTRY_MACHINE *m, STRING *u, time_t when);
+REGISTRY_MACHINE *registry_machine_allocate(const char *machine_guid, time_t when);
+REGISTRY_MACHINE *registry_machine_find_or_create(const char *machine_guid, time_t when, bool is_dummy);
+REGISTRY_MACHINE_URL *registry_machine_link_to_url(REGISTRY_MACHINE *m, STRING *url, time_t when);
+
+REGISTRY_MACHINE_URL *registry_machine_url_find(REGISTRY_MACHINE *m, STRING *url);
+void registry_machine_url_unlink_from_machine_and_free(REGISTRY_MACHINE *m, REGISTRY_MACHINE_URL *mu);
+
+#endif //NETDATA_REGISTRY_MACHINE_H
diff --git a/registry/registry_person.c b/registry/registry_person.c
new file mode 100644
index 00000000..4fd40fd7
--- /dev/null
+++ b/registry/registry_person.c
@@ -0,0 +1,232 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+#include "daemon/common.h"
+#include "registry_internals.h"
+
+// ----------------------------------------------------------------------------
+// PERSON_URL INDEX
+
+inline REGISTRY_PERSON_URL *registry_person_url_index_find(REGISTRY_PERSON *p, STRING *url) {
+    netdata_log_debug(D_REGISTRY, "Registry: registry_person_url_index_find('%s', '%s')", p->guid, string2str(url));
+
+    REGISTRY_PERSON_URL *pu;
+    for(pu = p->person_urls ; pu ;pu = pu->next)
+        if(pu->url == url)
+            break;
+
+    return pu;
+}
+
+inline REGISTRY_PERSON_URL *registry_person_url_index_add(REGISTRY_PERSON *p, REGISTRY_PERSON_URL *pu) {
+    DOUBLE_LINKED_LIST_PREPEND_ITEM_UNSAFE(p->person_urls, pu, prev, next);
+    return pu;
+}
+
+inline REGISTRY_PERSON_URL *registry_person_url_index_del(REGISTRY_PERSON *p, REGISTRY_PERSON_URL *pu) {
+    DOUBLE_LINKED_LIST_REMOVE_ITEM_UNSAFE(p->person_urls, pu, prev, next);
+    return pu;
+}
+
+// ----------------------------------------------------------------------------
+// PERSON_URL
+
+REGISTRY_PERSON_URL *registry_person_url_allocate(REGISTRY_PERSON *p, REGISTRY_MACHINE *m, STRING *url, char *machine_name, size_t machine_name_len, time_t when) {
+    netdata_log_debug(D_REGISTRY, "registry_person_url_allocate('%s', '%s', '%s'): allocating %zu bytes", p->guid, m->guid, string2str(url), sizeof(REGISTRY_PERSON_URL) + machine_name_len);
+
+    // protection from too big names
+    if(machine_name_len > registry.max_name_length)
+        machine_name_len = registry.max_name_length;
+
+    REGISTRY_PERSON_URL *pu = aral_mallocz(registry.person_urls_aral);
+
+    // a simple strcpy() should do the job,
+    // but I prefer to be safe, since the caller specified name_len
+    pu->machine_name = string_strdupz(machine_name);
+
+    pu->machine = m;
+    pu->first_t = pu->last_t = (uint32_t)when;
+    pu->usages = 1;
+    pu->url = string_dup(url);
+    pu->flags = REGISTRY_URL_FLAGS_DEFAULT;
+    m->links++;
+
+    netdata_log_debug(D_REGISTRY, "registry_person_url_allocate('%s', '%s', '%s'): indexing URL in person", p->guid, m->guid, string2str(url));
+    REGISTRY_PERSON_URL *tpu = registry_person_url_index_add(p, pu);
+    if(tpu != pu) {
+        netdata_log_error("Registry: Attempted to add duplicate person url '%s' with name '%s' to person '%s'", string2str(url), machine_name, p->guid);
+        string_freez(pu->machine_name);
+        string_freez(pu->url);
+        aral_freez(registry.person_urls_aral, pu);
+        pu = tpu;
+    }
+
+    return pu;
+}
+
+void registry_person_url_deindex_and_free(REGISTRY_PERSON *p, REGISTRY_PERSON_URL *pu) {
+    netdata_log_debug(D_REGISTRY, "registry_person_url_deindex_and_free('%s', '%s')", p->guid, string2str(pu->url));
+
+    REGISTRY_PERSON_URL *tpu = registry_person_url_index_del(p, pu);
+    if(tpu) {
+        string_freez(tpu->machine_name);
+        string_freez(tpu->url);
+        tpu->machine->links--;
+        aral_freez(registry.person_urls_aral, tpu);
+    }
+}
+
+// this function is needed to change the name of a PERSON_URL
+REGISTRY_PERSON_URL *registry_person_url_reallocate(REGISTRY_PERSON *p, REGISTRY_MACHINE *m, STRING *url, char *machine_name, size_t machine_name_len, time_t when, REGISTRY_PERSON_URL *pu) {
+    netdata_log_debug(D_REGISTRY, "registry_person_url_reallocate('%s', '%s', '%s'): allocating %zu bytes", p->guid, m->guid, string2str(url), sizeof(REGISTRY_PERSON_URL) + machine_name_len);
+
+    // keep a backup
+    REGISTRY_PERSON_URL pu2 = {
+            .first_t = pu->first_t,
+            .last_t = pu->last_t,
+            .usages = pu->usages,
+            .flags = pu->flags,
+            .machine = pu->machine,
+            .machine_name = NULL
+    };
+
+    // remove the existing one from the index
+    registry_person_url_deindex_and_free(p, pu);
+    pu = &pu2;
+
+    // allocate a new one
+    REGISTRY_PERSON_URL *tpu = registry_person_url_allocate(p, m, url, machine_name, machine_name_len, when);
+    tpu->first_t = pu->first_t;
+    tpu->last_t = pu->last_t;
+    tpu->usages = pu->usages;
+    tpu->flags = pu->flags;
+
+    return tpu;
+}
+
+
+// ----------------------------------------------------------------------------
+// PERSON
+
+REGISTRY_PERSON *registry_person_find(const char *person_guid) {
+    netdata_log_debug(D_REGISTRY, "Registry: registry_person_find('%s')", person_guid);
+    return dictionary_get(registry.persons, person_guid);
+}
+
+REGISTRY_PERSON *registry_person_allocate(const char *person_guid, time_t when) {
+    netdata_log_debug(D_REGISTRY, "Registry: registry_person_allocate('%s'): allocating new person, sizeof(PERSON)=%zu", (person_guid)?person_guid:"", sizeof(REGISTRY_PERSON));
+
+    REGISTRY_PERSON *p = aral_mallocz(registry.persons_aral);
+    if(!person_guid) {
+        for(;;) {
+            uuid_t uuid;
+            uuid_generate(uuid);
+            uuid_unparse_lower(uuid, p->guid);
+
+            netdata_log_debug(D_REGISTRY, "Registry: Checking if the generated person guid '%s' is unique", p->guid);
+            if (!dictionary_get(registry.persons, p->guid)) {
+                netdata_log_debug(D_REGISTRY, "Registry: generated person guid '%s' is unique", p->guid);
+                break;
+            }
+            else
+                netdata_log_info("Registry: generated person guid '%s' found in the registry. Retrying...", p->guid);
+        }
+    }
+    else
+        strncpyz(p->guid, person_guid, GUID_LEN);
+
+    p->person_urls = NULL;
+
+    p->first_t = p->last_t = (uint32_t)when;
+    p->usages = 0;
+
+    registry.persons_count++;
+    dictionary_set(registry.persons, p->guid, p, sizeof(REGISTRY_PERSON));
+
+    return p;
+}
+
+
+// 1. validate person GUID
+// 2. if it is valid, find it
+// 3. if it is not valid, create a new one
+// 4. return it
+REGISTRY_PERSON *registry_person_find_or_create(const char *person_guid, time_t when, bool is_dummy) {
+    netdata_log_debug(D_REGISTRY, "Registry: registry_person_find_or_create('%s'): creating dictionary of urls", person_guid);
+
+    char buf[GUID_LEN + 1];
+    REGISTRY_PERSON *p = NULL;
+
+    if(person_guid && *person_guid) {
+        // validate it is a GUID
+        if(unlikely(regenerate_guid(person_guid, buf) == -1)) {
+            netdata_log_info("Registry: person guid '%s' is not a valid guid. Ignoring it.", person_guid);
+            person_guid = NULL;
+        }
+        else {
+            person_guid = buf;
+            p = registry_person_find(person_guid);
+            if(!p && !is_dummy)
+                person_guid = NULL;
+        }
+    }
+    else
+        person_guid = NULL;
+
+    if(!p) p = registry_person_allocate(person_guid, when);
+
+    return p;
+}
+
+// ----------------------------------------------------------------------------
+// LINKING OF OBJECTS
+
+REGISTRY_PERSON_URL *registry_person_link_to_url(REGISTRY_PERSON *p, REGISTRY_MACHINE *m, STRING *url, char *machine_name, size_t machine_name_len, time_t when) {
+    netdata_log_debug(D_REGISTRY, "registry_person_link_to_url('%s', '%s', '%s'): searching for URL in person", p->guid, m->guid, string2str(url));
+
+    REGISTRY_PERSON_URL *pu = registry_person_url_index_find(p, url);
+    if(!pu) {
+        netdata_log_debug(D_REGISTRY, "registry_person_link_to_url('%s', '%s', '%s'): not found", p->guid, m->guid, string2str(url));
+        pu = registry_person_url_allocate(p, m, url, machine_name, machine_name_len, when);
+        registry.persons_urls_count++;
+    }
+    else {
+        netdata_log_debug(D_REGISTRY, "registry_person_link_to_url('%s', '%s', '%s'): found", p->guid, m->guid, string2str(url));
+        pu->usages++;
+        if(likely(pu->last_t < (uint32_t)when)) pu->last_t = (uint32_t)when;
+
+        if(pu->machine != m) {
+            REGISTRY_MACHINE_URL *mu = registry_machine_url_find(pu->machine, url);
+            if(mu) {
+                netdata_log_debug(D_REGISTRY, "registry_person_link_to_url('%s', '%s', '%s'): URL switched machines (old was '%s') - expiring it from previous machine.",
+                      p->guid, m->guid, string2str(url), pu->machine->guid);
+                mu->flags |= REGISTRY_URL_FLAGS_EXPIRED;
+            }
+            else {
+                netdata_log_debug(D_REGISTRY, "registry_person_link_to_url('%s', '%s', '%s'): URL switched machines (old was '%s') - but the URL is not linked to the old machine.",
+                      p->guid, m->guid, string2str(url), pu->machine->guid);
+            }
+
+            pu->machine->links--;
+            pu->machine = m;
+        }
+
+        if(strcmp(string2str(pu->machine_name), machine_name) != 0) {
+            // the name of the PERSON_URL has changed !
+            pu = registry_person_url_reallocate(p, m, url, machine_name, machine_name_len, when, pu);
+        }
+    }
+
+    p->usages++;
+    if(likely(p->last_t < (uint32_t)when)) p->last_t = (uint32_t)when;
+
+    if(pu->flags & REGISTRY_URL_FLAGS_EXPIRED) {
+        netdata_log_debug(D_REGISTRY, "registry_person_link_to_url('%s', '%s', '%s'): accessing an expired URL. Re-enabling URL.", p->guid, m->guid, string2str(url));
+        pu->flags &= ~REGISTRY_URL_FLAGS_EXPIRED;
+    }
+
+    return pu;
+}
+
+void registry_person_unlink_from_url(REGISTRY_PERSON *p, REGISTRY_PERSON_URL *pu) {
+    registry_person_url_deindex_and_free(p, pu);
+}
diff --git a/registry/registry_person.h b/registry/registry_person.h
new file mode 100644
index 00000000..4c2ca710
--- /dev/null
+++ b/registry/registry_person.h
@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+#ifndef NETDATA_REGISTRY_PERSON_H
+#define NETDATA_REGISTRY_PERSON_H 1
+
+#include "registry_internals.h"
+
+// ----------------------------------------------------------------------------
+// PERSON structures
+
+// for each PERSON-URL pair we keep this
+struct registry_person_url {
+    uint8_t flags;
+
+    uint32_t usages;            // how many times this has been accessed
+
+    uint32_t first_t;           // the first time we saw this
+    uint32_t last_t;            // the last time we saw this
+
+    REGISTRY_MACHINE *machine;  // link the MACHINE of this URL
+    STRING *machine_name;       // the hostname of the machine
+    STRING *url;                // de-duplicated URL
+
+    struct registry_person_url *prev, *next;
+};
+typedef struct registry_person_url REGISTRY_PERSON_URL;
+
+// A person
+struct registry_person {
+    char guid[GUID_LEN + 1];    // the person GUID
+
+    REGISTRY_PERSON_URL *person_urls;  // dictionary of PERSON_URLs
+
+    uint32_t first_t;           // the first time we saw this
+    uint32_t last_t;            // the last time we saw this
+    uint32_t usages;            // how many times this has been accessed
+};
+typedef struct registry_person REGISTRY_PERSON;
+
+// PERSON_URL
+REGISTRY_PERSON_URL *registry_person_url_index_find(REGISTRY_PERSON *p, STRING *url);
+REGISTRY_PERSON_URL *registry_person_url_index_add(REGISTRY_PERSON *p, REGISTRY_PERSON_URL *pu) NEVERNULL WARNUNUSED;
+REGISTRY_PERSON_URL *registry_person_url_index_del(REGISTRY_PERSON *p, REGISTRY_PERSON_URL *pu) WARNUNUSED;
+
+REGISTRY_PERSON_URL *registry_person_url_allocate(REGISTRY_PERSON *p, REGISTRY_MACHINE *m, STRING *url, char *machine_name, size_t machine_name_len, time_t when);
+REGISTRY_PERSON_URL *registry_person_url_reallocate(REGISTRY_PERSON *p, REGISTRY_MACHINE *m, STRING *url, char *machine_name, size_t machine_name_len, time_t when, REGISTRY_PERSON_URL *pu);
+
+// PERSON
+REGISTRY_PERSON *registry_person_find(const char *person_guid);
+REGISTRY_PERSON *registry_person_allocate(const char *person_guid, time_t when);
+REGISTRY_PERSON *registry_person_find_or_create(const char *person_guid, time_t when, bool is_dummy);
+
+// LINKING PERSON -> PERSON_URL
+REGISTRY_PERSON_URL *registry_person_link_to_url(REGISTRY_PERSON *p, REGISTRY_MACHINE *m, STRING *url, char *machine_name, size_t machine_name_len, time_t when);
+void registry_person_unlink_from_url(REGISTRY_PERSON *p, REGISTRY_PERSON_URL *pu);
+
+#endif //NETDATA_REGISTRY_PERSON_H