Change the way we pass information to urunit in Linux guests by cmainas · Pull Request #308 · urunc-dev/urunc

cmainas · 2025-10-21T17:00:38Z

Currently we are using the Linux kernel boot parameters to pass environment variables for the application execution in Linux VMs. Furthermore, urunit was responsible to properly handle the application arguments. However, this approach has the following limitations:

There was no way to pass more information for the application execution inside the Linux guest (e.g. working dir, uid etc.).
The Linux kernel boot parameters has a limit of characters that can handle and in case we have too many environment variables or a lot of arguments for the application, we are risking to hit that limit. We observed such cases in k8s deployments with many services, where k8s adds environment variables for each deployed service.
With Linux kernel boot parameters, we could not pass any non-POSIX environment variables, which unfortunately are used from some containers.

For all the above reason, we change the way we pass information to urunit by using "urunit configuration file" instead of kernel boot parameters. In particular, if we set the URUNIT_CONFIG environment variable to point to a file, then urunit will try to parse this file and expects to read the following configuration format:

UES
/* list of environment variables */
UEE
UCS
UID:<uid>
GID:<gid>
WD:<working_dir>
UCE

Parsing a confguration like this, urunit will set the environment variables for the application execution, the uid,gid and at last switch to the working directory for the application.

In order to minimize the dependencies for the Linux kernel running as guest, we choose to pass this file as an initrd and set the retain_initrd kernel boot parameter. In that way, urunit can mount sysfs at /sys and read the configuration file from /sys/firmware/initrd where the Linux kernel will store the initrd. In case the guest is configured to boot with an initrd, then urunc will archive the configuration file using the cpio format and concatenate it with the user specified initrd. The linux kernel is smart enough to properly unpack concatenated initrd and hence the urunit configuration file will appear in the guest rootfs. Therefore, with that method, there are only the following requirements for the guest kernel:

Support for initrd CONFIG_BLK_DEV_INITRD
Support for sysfs CONFIG_SYSFS

Of course, urunc fills the above configuration, based on the container's configuration and specifically, the Process struct of the spec.

netlify · 2025-10-21T17:00:47Z

✅ Deploy Preview for urunc ready!

Name	Link
🔨 Latest commit	`1aa48ec`
🔍 Latest deploy log	https://app.netlify.com/projects/urunc/deploys/68fde32619126100080ce827
😎 Deploy Preview	https://deploy-preview-308--urunc.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

ananos

thanks @cmainas, LGTM!

There are cases where containers use non-POSIX environment variables or cases where the environment variables can exceed the limit of characters in Linux kernel boot parameters. Therefore, the environment variables were not set correctly. To fix the above issue, we change the way we pass the environment variables to the guest in Linux with the the help of urunit. In particular, instead of using the Linux kernel boot parameters, we use store the environment variables in a file and let urunit read that file and set the environment variables for the application inside the Linux VM. In order to minimize the depedencies of the guest kernel and provide a croos-monitor solution, we pass the urunit configuration file as an initrd for the guest and instruct Linux kernel to keep it with the retain_initrd kernel boot parameter. In that way, urunit simply reads the contents of /sys/firmware/initrd and is able to get the configuration file. If the guest is configured to use an initrd then we format the urunit configuration file in the cpio format and concatenate the user provided initrd with the one we created for the urunit configuration file. The Linux kernel is able to properly extract concatenated initrds and therefore the configuration file will appear in the rootfs of the VM. PR: #308 Signed-off-by: Charalampos Mainas <cmainas@nubificus.co.uk> Reviewed-by: Anastassios Nanos <ananos@nubificus.co.uk> Approved-by: Anastassios Nanos <ananos@nubificus.co.uk>

The guest can append further cli args for the monitor, since the VMM interface calls the MonitorCli function. However, this function was not compatible with Firecracker, which uses a json configuration file to define the VM arguments. THis commit partially fixes this by updating the return value of MonitorCli, in order to use a new struct. The current implementation was also necessary for Linux to define the extra initrd file with the urunit configuration. Therefore, for the time being the MonitrCliArgs consists of only two fields, one for initr and one for other cli args. However, in the future we can iterate over it and update it. PR: #308 Signed-off-by: Charalampos Mainas <cmainas@nubificus.co.uk> Reviewed-by: Anastassios Nanos <ananos@nubificus.co.uk> Approved-by: Anastassios Nanos <ananos@nubificus.co.uk>

Update the urunit configuration file to enable passing extra information for the execution environment of the application inside the Linux VM. In particular, this commit passess the following information to urunit: - uid of the Linux process inside the VM - gid of the Linux process inside the VM - working directory of the Linux process inside the VM The format that is used is the following: UES /* env vars */ UEE UCS UID:<uid> GID:<gid> WD:<working_directory> UCE PR: #308 Signed-off-by: Charalampos Mainas <cmainas@nubificus.co.uk> Reviewed-by: Anastassios Nanos <ananos@nubificus.co.uk> Approved-by: Anastassios Nanos <ananos@nubificus.co.uk>

Update the tutorail for running existing containers over Linux in urunc in order to include the new changes on passing information to the guest from the host. PR: #308 Signed-off-by: Charalampos Mainas <cmainas@nubificus.co.uk> Reviewed-by: Anastassios Nanos <ananos@nubificus.co.uk> Approved-by: Anastassios Nanos <ananos@nubificus.co.uk>

Update the prvious tests in Linux for environment variables to also check the correct setting of uid,gid and working directory except of the environment variables. PR: #308 Signed-off-by: Charalampos Mainas <cmainas@nubificus.co.uk> Reviewed-by: Anastassios Nanos <ananos@nubificus.co.uk> Approved-by: Anastassios Nanos <ananos@nubificus.co.uk>

There are cases where containers use non-POSIX environment variables or cases where the environment variables can exceed the limit of characters in Linux kernel boot parameters. Therefore, the environment variables were not set correctly. To fix the above issue, we change the way we pass the environment variables to the guest in Linux with the the help of urunit. In particular, instead of using the Linux kernel boot parameters, we use store the environment variables in a file and let urunit read that file and set the environment variables for the application inside the Linux VM. In order to minimize the depedencies of the guest kernel and provide a croos-monitor solution, we pass the urunit configuration file as an initrd for the guest and instruct Linux kernel to keep it with the retain_initrd kernel boot parameter. In that way, urunit simply reads the contents of /sys/firmware/initrd and is able to get the configuration file. If the guest is configured to use an initrd then we format the urunit configuration file in the cpio format and concatenate the user provided initrd with the one we created for the urunit configuration file. The Linux kernel is able to properly extract concatenated initrds and therefore the configuration file will appear in the rootfs of the VM. PR: #308 Signed-off-by: Charalampos Mainas <cmainas@nubificus.co.uk> Reviewed-by: Anastassios Nanos <ananos@nubificus.co.uk> Approved-by: Anastassios Nanos <ananos@nubificus.co.uk>

The guest can append further cli args for the monitor, since the VMM interface calls the MonitorCli function. However, this function was not compatible with Firecracker, which uses a json configuration file to define the VM arguments. THis commit partially fixes this by updating the return value of MonitorCli, in order to use a new struct. The current implementation was also necessary for Linux to define the extra initrd file with the urunit configuration. Therefore, for the time being the MonitrCliArgs consists of only two fields, one for initr and one for other cli args. However, in the future we can iterate over it and update it. PR: #308 Signed-off-by: Charalampos Mainas <cmainas@nubificus.co.uk> Reviewed-by: Anastassios Nanos <ananos@nubificus.co.uk> Approved-by: Anastassios Nanos <ananos@nubificus.co.uk>

Update the urunit configuration file to enable passing extra information for the execution environment of the application inside the Linux VM. In particular, this commit passess the following information to urunit: - uid of the Linux process inside the VM - gid of the Linux process inside the VM - working directory of the Linux process inside the VM The format that is used is the following: UES /* env vars */ UEE UCS UID:<uid> GID:<gid> WD:<working_directory> UCE PR: #308 Signed-off-by: Charalampos Mainas <cmainas@nubificus.co.uk> Reviewed-by: Anastassios Nanos <ananos@nubificus.co.uk> Approved-by: Anastassios Nanos <ananos@nubificus.co.uk>

Update the tutorail for running existing containers over Linux in urunc in order to include the new changes on passing information to the guest from the host. PR: #308 Signed-off-by: Charalampos Mainas <cmainas@nubificus.co.uk> Reviewed-by: Anastassios Nanos <ananos@nubificus.co.uk> Approved-by: Anastassios Nanos <ananos@nubificus.co.uk>

sonarqubecloud · 2025-10-26T09:00:55Z

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
2.3% Duplication on New Code

See analysis details on SonarQube Cloud

cmainas added the ok-to-test label Oct 22, 2025

cmainas force-pushed the feat_env_config_urunit branch 2 times, most recently from d50236a to 18d2f94 Compare October 22, 2025 15:47

cmainas marked this pull request as ready for review October 22, 2025 16:07

cmainas requested a review from ananos October 22, 2025 16:07

cmainas force-pushed the feat_env_config_urunit branch from 18d2f94 to 55837c9 Compare October 22, 2025 16:54

This was linked to issues Oct 23, 2025

Configure the execution environment inside a Linux VM #253

Closed

Change the way we pass environment variables in Linux containers #254

Closed

cmainas force-pushed the feat_env_config_urunit branch from 55837c9 to cc7d667 Compare October 23, 2025 10:24

ananos approved these changes Oct 26, 2025

View reviewed changes

cmainas added 5 commits October 26, 2025 09:00

github-actions Bot force-pushed the feat_env_config_urunit branch from cc7d667 to 1aa48ec Compare October 26, 2025 09:00

urunc-bot Bot merged commit 4010ca7 into main Oct 26, 2025
5 of 7 checks passed

ananos deleted the feat_env_config_urunit branch October 26, 2025 09:00

This was referenced Oct 27, 2025

Configure the execution environment inside a Linux VM #253

Closed

Change the way we pass environment variables in Linux containers #254

Closed

namansh70747 mentioned this pull request Apr 13, 2026

feat(unikernels): pass OCI rlimits to urunit config #558

Open

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Change the way we pass information to urunit in Linux guests#308

Change the way we pass information to urunit in Linux guests#308
urunc-bot[bot] merged 5 commits intomainfrom
feat_env_config_urunit

cmainas commented Oct 21, 2025

Uh oh!

netlify Bot commented Oct 21, 2025 •

edited

Loading

Uh oh!

ananos left a comment

Uh oh!

Uh oh!

sonarqubecloud Bot commented Oct 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

cmainas commented Oct 21, 2025

Uh oh!

netlify Bot commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for urunc ready!

Uh oh!

ananos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sonarqubecloud Bot commented Oct 26, 2025

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

netlify Bot commented Oct 21, 2025 •

edited

Loading