From d9ad3b2c12cf51ddd168f46890b90d4e4f7f2410 Mon Sep 17 00:00:00 2001 From: Przemek Maciolek Date: Tue, 22 Feb 2022 13:19:00 +0100 Subject: [PATCH 1/4] Set instance_uid by Server on conflict or request for generation --- specification.md | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/specification.md b/specification.md index cd41e38..14cb829 100644 --- a/specification.md +++ b/specification.md @@ -105,9 +105,9 @@ ServerToAgent Protobuf messages: Typically a single Server accepts WebSocket connections from many agents. Agents -are identified by self-assigned globally unique instance identifiers (or -instance_uid for short). The instance_uid is recorded in each message sent from -the Agent to the Server and from the Server to the Agent. +are identified by self-assigned or server-assigned globally unique instance +identifiers (or instance_uid for short). The instance_uid is recorded in each +message sent from the Agent to the Server and from the Server to the Agent. The default URL path for the initial WebSocket's HTTP connection is /v1/opamp. The URL path MAY be configurable on the Agent and on the Server. @@ -175,6 +175,9 @@ created by other Agents. The instance_uid SHOULD remain unchanged for the lifetime of the agent process. The recommended format for the instance_uid is [ULID](https://github.com/ulid/spec). +In case the Agent wants to use an identifier generated by the Server, the field +MAY be unset. + #### status_report The status of the Agent. MUST be set in the first AgentToServer message that the @@ -254,11 +257,19 @@ message ServerToAgent { #### instance_uid -The Agent instance identifier. MUST match the instance_uid field previously -received in the AgentToServer message. When communication with multiple Agents -is multiplexed into one WebSocket connection (for example when a terminating -proxy is used) the instance_uid field allows to distinguish which Agent the -ServerToAgent message is addressed to. +The Agent instance identifier. + +If UpdateInstanceUid flag is set then Agent MUST update its instance_uid to +the provided value (e.g. either because a conflict was detected or an empty +instance_uid was sent previously to the Server, indicating a request for +generating new identifier). + +If UpdateInstanceUid flag is not set, the value MUST match the instance_uid +field previously received in the AgentToServer message. + +When communication with multiple Agentsis multiplexed into one WebSocket +connection (for example when a terminating proxy is used) the instance_uid field +allows to distinguish which Agent the ServerToAgent message is addressed to. #### error_response @@ -318,6 +329,9 @@ enum Flags { // set if the Agent indicated it cannot report addon status by setting // the ReportsAddonStatus bit to 0 in StatusReport.capabilities field. ReportAddonStatus = 0x00000002; + + // The server requests the agent to change its instance_uid to the provided value. + UpdateInstanceUid = 0x00000003; } ``` From 22fc2081e159ff446ec09795fe73a405979301ae Mon Sep 17 00:00:00 2001 From: Przemek Maciolek <58699843+pmm-sumo@users.noreply.github.com> Date: Wed, 23 Feb 2022 21:34:02 +0100 Subject: [PATCH 2/4] Update specification.md Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> --- specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification.md b/specification.md index 14cb829..990e2a1 100644 --- a/specification.md +++ b/specification.md @@ -331,7 +331,7 @@ enum Flags { ReportAddonStatus = 0x00000002; // The server requests the agent to change its instance_uid to the provided value. - UpdateInstanceUid = 0x00000003; + UpdateInstanceUid = 0x00000004; } ``` From 1bbcce153d93350229e32341e16940c94a50853d Mon Sep 17 00:00:00 2001 From: Przemek Maciolek Date: Tue, 8 Mar 2022 16:37:44 -0800 Subject: [PATCH 3/4] Use separate field and explicit flag for server-assigned instance_uid --- specification.md | 58 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 39 insertions(+), 19 deletions(-) diff --git a/specification.md b/specification.md index 990e2a1..8d9f7e1 100644 --- a/specification.md +++ b/specification.md @@ -159,6 +159,7 @@ message AgentToServer { AgentAddonStatuses addon_statuses = 3; AgentInstallStatus agent_install_status = 4; AgentDisconnect agent_disconnect = 5; + AgentToServerFlags flags = 6; } ``` @@ -176,7 +177,7 @@ lifetime of the agent process. The recommended format for the instance_uid is [ULID](https://github.com/ulid/spec). In case the Agent wants to use an identifier generated by the Server, the field -MAY be unset. +SHOULD be set with a temporary value and RequestInstanceUid flag MUST be set. #### status_report @@ -202,6 +203,23 @@ the last AgentToServer message. AgentDisconnect MUST be set in the last AgentToServer message sent from the agent to the server. +#### flags + + +Bit flags as defined by AgentToServerFlags bit masks. + +```protobuf +enum AgentToServerFlags { + FlagsUnspecified = 0; + + // Flags is a bit mask. Values below define individual bits. + + // The agent requests server go generate a new instance_uid, which will + // be sent back in ServerToAgent message + RequestInstanceUid = 0x00000001; +} +``` + ## ServerToAgent Message @@ -257,19 +275,15 @@ message ServerToAgent { #### instance_uid -The Agent instance identifier. +The Agent instance identifier. MUST match the instance_uid field previously +received in the AgentToServer message. When communication with multiple Agents +is multiplexed into one WebSocket connection (for example when a terminating +proxy is used) the instance_uid field allows to distinguish which Agent the +ServerToAgent message is addressed to. -If UpdateInstanceUid flag is set then Agent MUST update its instance_uid to -the provided value (e.g. either because a conflict was detected or an empty -instance_uid was sent previously to the Server, indicating a request for -generating new identifier). - -If UpdateInstanceUid flag is not set, the value MUST match the instance_uid -field previously received in the AgentToServer message. - -When communication with multiple Agentsis multiplexed into one WebSocket -connection (for example when a terminating proxy is used) the instance_uid field -allows to distinguish which Agent the ServerToAgent message is addressed to. +Note: If UpdateInstanceUid flag is set then Agent MUST update its instance_uid to +the value provided in AgentRemoteConfig and use it for further communication. +value. #### error_response @@ -1692,9 +1706,14 @@ The message has the following structure: ```protobuf message AgentRemoteConfig { AgentConfigMap config = 1; + string new_instance_uid = 2; } ``` +When UpdateInstanceUid flag is set, new_instance_uid MUST be not empty, Agent +MUST update instance_uid to the value provided in it and use it for all further +communication. +

Addons

@@ -2150,10 +2169,11 @@ The Server MAY disconnect or deny serving requests if it detects that the same Agent instance has more than one simultaneous connection or if multiple Agent instances are using the same instance_uid. -Open Question: does the Server need to actively detect duplicate instance_uids, -which may happen due to Agents using bad UID generators which create globally -non-unique UIDs or for example because of cloning of the VMs where the Agent -runs? +The Server SHOULD detect duplicate instance_uids (which may happen for example +when Agents are using bad UID generators or due to cloning of the VMs where the +Agent runs). When a duplicate instance_uid is detected, Server SHOULD generate +a new instance_uid, set UpdateInstanceUid flag of ServerToAgent message and +set the new_instance_uid value in AgentRemoteConfig.

Authentication

@@ -2452,9 +2472,9 @@ TBD * ~~Do we need the sequence_num concept?~~ Deleted for now, not necessary for current feature set, but may need to be restored for other features (e.g. custom "extensions"). -* Does the Server need to actively detect duplicate instance_uids, which may +* ~~Does the Server need to actively detect duplicate instance_uids, which may happen due to Agents using bad UID generators which create globally non-unique - UIDs? + UIDs?~~ Added. * ~~Do we need to split the AddonStatus and AgentStatus from the general StatusReport?~~ Yes, splitted. * Does WebSocket frame compression work for us or do we need our own mechanism? From 1ae9135854bfff86b68ed9d6b3a373f632f53d46 Mon Sep 17 00:00:00 2001 From: Przemek Maciolek Date: Thu, 10 Mar 2022 16:57:30 -0800 Subject: [PATCH 4/4] Use separate field for agent identification --- specification.md | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/specification.md b/specification.md index 8d9f7e1..85c8db2 100644 --- a/specification.md +++ b/specification.md @@ -269,6 +269,7 @@ message ServerToAgent { AgentPackageAvailable agent_package_available = 6; Flags flags = 7; ServerCapabilities capabilities = 8; + AgentIdentification agent_identification = 9; } ``` @@ -281,9 +282,9 @@ is multiplexed into one WebSocket connection (for example when a terminating proxy is used) the instance_uid field allows to distinguish which Agent the ServerToAgent message is addressed to. -Note: If UpdateInstanceUid flag is set then Agent MUST update its instance_uid to -the value provided in AgentRemoteConfig and use it for further communication. -value. +Note: the value can be overriden by server by sending a new one in the +AgentIdentification field. When this happens then Agent MUST update its +instance_uid to the value provided and use it for all further communication. #### error_response @@ -343,9 +344,6 @@ enum Flags { // set if the Agent indicated it cannot report addon status by setting // the ReportsAddonStatus bit to 0 in StatusReport.capabilities field. ReportAddonStatus = 0x00000002; - - // The server requests the agent to change its instance_uid to the provided value. - UpdateInstanceUid = 0x00000004; } ``` @@ -385,6 +383,17 @@ enum ServerCapabilities { } ``` +#### agent_identification + +Properties related to identification of the agent, which can be overriden by the +server if needed. When new_instance_uid is set, Agent MUST update instance_uid +to the value provided and use it for all further communication. + +```protobuf +message AgentIdentification { + string new_instance_uid = 1; +} +```

ServerErrorResponse Message

@@ -1706,14 +1715,9 @@ The message has the following structure: ```protobuf message AgentRemoteConfig { AgentConfigMap config = 1; - string new_instance_uid = 2; } ``` -When UpdateInstanceUid flag is set, new_instance_uid MUST be not empty, Agent -MUST update instance_uid to the value provided in it and use it for all further -communication. -

Addons

@@ -2172,8 +2176,7 @@ instances are using the same instance_uid. The Server SHOULD detect duplicate instance_uids (which may happen for example when Agents are using bad UID generators or due to cloning of the VMs where the Agent runs). When a duplicate instance_uid is detected, Server SHOULD generate -a new instance_uid, set UpdateInstanceUid flag of ServerToAgent message and -set the new_instance_uid value in AgentRemoteConfig. +a new instance_uid, and send it as new_instance_uid value of AgentIdentification.

Authentication