Support unix domain sockets by christoph-hamm · Pull Request #784 · eclipse-ankaios/ankaios

christoph-hamm · 2026-08-27T07:10:43Z

Issues: #780

Definition of Done

The PR shall be merged only if all items mentioned in CONTRIBUTING.md have been followed. In case an item is not applicable as described, please provide a short explanation in the description.

All steps in CONTRIBUTING.md have been handled

ToDo

christoph-hamm · 2026-08-27T10:00:36Z

The domains sockets have been added to the ank-server, ank-agent and ank. The devcontainer config, debian package and the install script have been updated as well. All three are working. Only for devcontainer the stests are not working at the moment.

I have not checked the documentation yet, if everything is still working. I think we need to mention the new ankaios group, and that you have to be part of that group in order to use the ankaios CLI. We can also remove the warning in the documentation.

sonarqubecloud · 2026-09-25T12:33:38Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
91.6% Coverage on New Code
0.3% Duplication on New Code

See analysis details on SonarQube Cloud

krucod3 · 2026-09-28T12:14:30Z

I'll start with the review here.

krucod3

Initial review done. Configs and documentation are now reviewed. I'll continue with the rest now.

krucod3 · 2026-09-29T06:15:08Z


+fn validate_socket_configuration(agent_config: &AgentConfig) -> Result<(), String> {
+    validate_unix_socket_tls_settings(
+        "agent",


I somehow don't like this string here ...

At the end it's mean to reduce code duplications, but the or below is still repeated and we have a freely configurable string as input. The logic in the common function is also not really complex. Maybe just providing common functions is_unix is is_tcp would make more sense.

I have removed the the parameter. The call as now using map_err to adding a prefix.

krucod3 · 2026-09-29T11:15:48Z

-# The server url.
-# server_url = 'https://127.0.0.1:25551'
+# The server endpoint.
+address = 'unix:///run/ankaios/server.sock'


Why renaming here? A domain socket is still specified by a url which includes also the protocol, in this case "unix://"

Changed it back to URL.

krucod3 · 2026-09-29T11:24:54Z

+    if address.starts_with("https://") || address.starts_with("http://") {
+        Ok(())


So if only https:// it's OK?

The code is now changed, as the URL is more early put in an enum to distinguish HTTP from UDS. But the logic is still the same, for UDS we check it is not empty, for URL we do not. For UDS the check is primarily there, to check for an absolute path, and returning an error saying it is not absolute for an empty path would be strange, hence the special handling for empty. For HTTP it is as before. If we start checking we could add more and more checks to see it is an valid HTTP URL, and I do not want to start this.

krucod3 · 2026-09-29T11:44:22Z

+    )]
+    /// The server endpoint.
+    /// Supported values are https://host:port and unix:///path/to/socket.
+    pub address: Option<String>,


Again, I don't understand why we want to change the external interface of the agent. server url is already correct.

It is back to server_url.

krucod3 · 2026-10-05T06:40:04Z

+    let tls_config = if agent_config.address.starts_with("unix://") {
+        None
+    } else {
+        if let Err(err_message) = TLSConfig::is_config_conflicting(
+            agent_config.insecure,
+            &agent_config.ca_pem_content,
+            &agent_config.crt_pem_content,
+            &agent_config.key_pem_content,
+        ) {
+            log::warn!("{err_message}");
+        }


This is a bit strange now. We already did some checks about TLS, insecure and connection type, and now we start to create the TLS config and ignore the uds connections ...
I have not looked in detail and there are some differences between server and agent/ank handling, but maybe there is a better way to organize the config handling.

We checked if the config is valid before, and now we only create the tls config if it is needed. Maybe at the initial check we could create some enum structure which only allow valid configuration and which might remove some checks here, or something similar with traits. I think it is OK as it is and would not change it.

krucod3 · 2026-10-05T06:41:46Z

 # If set to 'true' and the certificates are not provided, then the server shall not use TLS.
-insecure = false
+# This option must not be used with 'unix://' addresses.
+# insecure = true


I think we should leave the default to false also in the example.

Set it to false again.

krucod3 · 2026-10-05T06:43:45Z

+    If no `address` is configured and no configuration file is used, the Ankaios server defaults to
+    the TCP address `127.0.0.1:25551`.


So if nothing is configured, Ankaios does not start?
default url is http and insecure is per default false. No default tls config => fail to start. Maybe default should be uds.

Below there is another paragraph stating that the default is the domain socket:
https://github.com/eclipse-ankaios/ankaios/pull/784/changes#diff-f37a7d24bc9ebf61ff0c5e3165666b5590ba702a6ad912760833cfd3024f855eR50-R52

Which one is correct?

If you have no configuration files, the default is 127.0.0.1:5551 but as no certificates are provided, it will not start. I was also thinking about changing it to UDS as default, but this would be a breaking change. E.g. a user has a configuration files only configuring the certificate, the server would now start listening on the default https://127.0.01:5551. If we would now make UDS the default, it would not listen to localhost anymore or crash for wrong configuration (depending on whether we are changing this or not).

The thing below ist about the default installation methods. Here some configuration files are installed as well, which default to UDS.

krucod3 · 2026-10-05T06:49:29Z

+}
+
+pub fn validate_server_address_format(address: &str) -> Result<(), String> {
+    if let Some(path) = address.strip_prefix("unix://") {


Please introduce constants for the protocol identifiers.

krucod3 · 2026-10-05T08:34:03Z

+
+```toml
+address = 'https://127.0.0.1:25551'
+insecure = false


We don't need the false here as it is default.

krucod3

Review the rest without tools folder. Will review this one after all changes there are pushed.

krucod3 · 2026-10-05T08:56:54Z

 - itest

+#### gRPC Server supports unix domain socket endpoints
+`swdd~grpc-server-supports-unix-domain-socket-endpoints~1`


And the client does not need anything?
We should add another req for the client too.

I have added an requirements for the client.

krucod3 · 2026-10-05T08:58:14Z

+
+Status: approved
+
+The gRPC Server shall support listening for incoming gRPC connections on either a TCP socket endpoint or a Unix domain socket endpoint.


The name is about Unix domain sockets, but the description mentions either TCP or Unix sockets.

Updated the description.

krucod3 · 2026-10-05T09:01:31Z

+The gRPC Server shall support listening for incoming gRPC connections on either a TCP socket endpoint or a Unix domain socket endpoint.
+
+Rationale:
+Unix domain sockets allow local communication without exposing a TCP port.


But requires a socket. That's not a rationale. Suggestion:

Suggested change

Unix domain sockets allow local communication without exposing a TCP port.

Unix domain sockets are faster and allow securing local communication using IAM improving the ease of use.

I took you rational but dropped the "faster" part, as this was not a reason we added them.

krucod3 · 2026-10-05T09:02:44Z

+fn parse_server_endpoint(
+    server_address: &String,


I still think calling is url instead of endpoint or address is more precise.

It is URL again.

krucod3 · 2026-10-05T11:40:14Z

+- utest
+


We could also stest the group setting and the permissions.

We could but I am not sure if it is worth it. We have to ensure the test user has supplementary group we can use for the test. We also have to ensure the umask does not produce the wanted file permissions.

I see it like this: we have tested in manually and it works, and I think it is unlikely it is removed or changed accidentally, as we also have utest for this.

krucod3 · 2026-10-05T12:16:32Z

+        let server_config_content = r"#
+        version = 'v1'
+        address = 'unix:///tmp/ankaios-server.sock'
+        ca_pem = '/tmp/.certs/ca.pem'


ca_pem_content is not tested.

Added unit test for ca_pem_content.

krucod3 · 2026-10-05T12:18:57Z

 ${AGENT_NAME}=    agent_A
 ${AGENT_2_NAME}=    agent_B
 ${ANKAIOS_TMP_FOLDER}=    /tmp/ankaios
+${ANKAIOS_SERVER_URL}=    unix:///tmp/ankaios.sock


I would go for a more prescriptive name containing UDS or UNIX, etc.

Renamed it to ANKAIOS_SERVER_SOCKET_URL.

krucod3 · 2026-10-05T12:36:56Z

+    Set Environment Variable    name=ANKSERVER_SERVER_URL    value=${ANKAIOS_SERVER_URL}
+    Set Environment Variable    name=ANKAGENT_SERVER_URL    value=${ANKAIOS_SERVER_URL}
+    Set Environment Variable    name=ANK_SERVER_URL    value=${ANKAIOS_SERVER_URL}


So now the stests could leave the environment changed in case the variables were not set.
I get the intention as they are normally ran by as in the devcontainer and there we have the variable as you are setting it now.

Let's go for this solution for now. If we get into trouble we could think about using configs in the dev environment and unsetting the vars here.

I do not know what you mean here? Is your idea you start a shell, execute the stests and afterwards the environment variables of you shell are different? This will never happen as a child process can not change the environment variables of the parent process.

krucod3 · 2026-10-05T12:38:49Z

    And the workload "hello3" shall have the execution state "Pending(Initial)" on agent "agent_B"
    # Actions
-    When user triggers "ank -k get agents"
+    When user triggers "ank get agents"


🎆 Yeah! Finally get rid of the -k 👍

krucod3

The changes in the tools are now reviewed too and look good 👍

Co-authored-by: Kaloyan <36224699+krucod3@users.noreply.github.com>

christoph-hamm force-pushed the 780_support-unix-domain-sockets branch from d1adf6c to b580024 Compare August 27, 2026 08:23

christoph-hamm added the enhancement New feature or request. Issue will appear in the change log "Features" label Aug 27, 2026

christoph-hamm linked an issue Aug 27, 2026 that may be closed by this pull request

Support Unix Domain Sockets #780

Open

3 tasks

christoph-hamm added 13 commits September 24, 2026 15:48

Add support for unix domain sockets to ank-server

5cffff3

Add domain socket support to ank-agent

a0745d1

Support unix domain sockets in the ank CLI

e8fa268

Use domain sockets in devcontainer

389a35d

Update install script to use unix domain socket

47d3434

Use unix domain socket in debian package

066dd83

Deduplicate code

4d5fa85

Add unit test for unix socket setup

d72fe60

Exclude unused trait imports from test

fbd4c9f

Adapt stests

93b82d5

Include unix sockets in documentation

882732d

Print error if ank.conf exists but is invalid

6a0268b

Add needed group for unix socket to AUR packages

53f0cad

christoph-hamm force-pushed the 780_support-unix-domain-sockets branch from d97f7da to 53f0cad Compare September 24, 2026 13:54

Fix address setup in system tests

c33a3b6

christoph-hamm added the ready for review label Sep 25, 2026

christoph-hamm mentioned this pull request Sep 28, 2026

Support Unix Domain Sockets #780

Open

3 tasks

krucod3 self-requested a review September 28, 2026 12:14

windsource reviewed Sep 29, 2026

View reviewed changes

Comment thread tools/debian/build_src_pkg.sh Outdated

krucod3 reviewed Oct 5, 2026

View reviewed changes

Update utests to thread_local OPS to improve debugging

e909d44

krucod3 reviewed Oct 5, 2026

View reviewed changes

Update used socket file and run folder

f59147e

krucod3 reviewed Oct 5, 2026

View reviewed changes

christoph-hamm and others added 19 commits October 7, 2026 13:48

Improve description insecure flag

a850630

Co-authored-by: Kaloyan <36224699+krucod3@users.noreply.github.com>

Improve handling of differnt connection type and rename to URL

02bc01c

Do not hand arbitrary string to validate_tls_function

fc41dd0

Add test for wrong scheme in server address

233274a

Use insecure = false in example, as it was before

26e064c

Removed unneeded configuration from Network Setup page

9fd3e08

Improve name for Unix socket endpoint

7095d02

Co-authored-by: Kaloyan <36224699+krucod3@users.noreply.github.com>

Improve name on requirements for Unix sockets

5010db2

Add more tracing for unix socket implementation

032edc8

Add requirements for grpc client code supporting UDS

25f51f4

Improve requirements and tracing of socket access rights

87ee9ea

Add needs utest

3a34d3f

Co-authored-by: Kaloyan <36224699+krucod3@users.noreply.github.com>

Fix names of utests

e9be500

Improve name of requirement

aeb197d

Add requirement for valid socket configurations in agent and client

d78c496

Add requirement and utest for empty group name not allowed

8f281a2

Add unit test for reject unix socket with ca_pem_content

8ccca3f

Change name constant for stest holding server URL

a92fb1f

Undo some more renames from URL to address

bb4482e

		if address.starts_with("https://") \|\| address.starts_with("http://") {
		Ok(())

		If no `address` is configured and no configuration file is used, the Ankaios server defaults to
		the TCP address `127.0.0.1:25551`.


		Status: approved

		The gRPC Server shall support listening for incoming gRPC connections on either a TCP socket endpoint or a Unix domain socket endpoint.

	Unix domain sockets allow local communication without exposing a TCP port.
	Unix domain sockets are faster and allow securing local communication using IAM improving the ease of use.

Conversation

christoph-hamm commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Definition of Done

ToDo

Uh oh!

christoph-hamm commented Aug 27, 2026

Uh oh!

sonarqubecloud Bot commented Sep 25, 2026

Quality Gate passed

Uh oh!

krucod3 commented Sep 28, 2026

Uh oh!

Uh oh!

krucod3 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

christoph-hamm Oct 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

christoph-hamm Oct 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

krucod3 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

christoph-hamm commented Aug 27, 2026 •

edited

Loading

christoph-hamm Oct 7, 2026 •

edited

Loading

christoph-hamm Oct 7, 2026 •

edited

Loading