Skip to content

Commit 8c21c19

Browse files
committed
docs(cluster): say why the boot daemon sets HOME
1 parent 6e0b90c commit 8c21c19

2 files changed

Lines changed: 2 additions & 2 deletions

File tree

‎roles/github_runner_cluster/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -153,7 +153,7 @@ The role reads what it needs to tell a Mac from another host (the kernel name) a
153153

154154
A Mac still has to log in for the agent to run: a launch agent starts with the user's login session, not with the machine. A host whose profile is started by an agent, and that should recover from a reboot unattended, needs automatic login for that user (System Settings > Users & Groups), which FileVault prevents. The k3s node's profile does not depend on it:
155155

156-
**At boot (a daemon).** For the profile that runs the node the role installs a launchd daemon instead, `com.exadev.github-runner.colima.<profile>`, as `/Library/LaunchDaemons/<label>.plist`, owned by `root:wheel` with mode `0644` (launchd refuses a daemon property list that anyone else can write), and loads it into the `system` domain (`launchctl bootstrap system <plist>`). A daemon runs when the Mac starts, whether or not anyone has logged in, so the profile and the node's container come back after a power loss with the Mac sitting at the login window. The daemon runs the same command with the same `PATH` and `COLIMA_HOME` as the agent does, as the connecting user (`UserName`, which launchd honours only for a job loaded into the system domain, and ignores for an agent: `man launchd.plist` on a Mac), with that user's `HOME` set in its environment, because Colima and Lima read the home directory from it and a daemon's environment is otherwise bare. Its log is in the user's `~/Library/Logs`, as the agent's is. Writing the property list and loading it take root, so the role uses `become` for these tasks and nothing else in the runtime tasks: run the play with passwordless sudo for the connecting user (the `github_runner_macos_host` role's `github_runner_macos_host_sudoers_nopasswd` grants it) or with `--ask-become-pass`. Colima's network helper (`socket_vmnet`) and its sudoers entry are the user's, installed the first time a profile with an address starts, and the daemon runs as the same user, so it needs nothing the agent did not.
156+
**At boot (a daemon).** For the profile that runs the node the role installs a launchd daemon instead, `com.exadev.github-runner.colima.<profile>`, as `/Library/LaunchDaemons/<label>.plist`, owned by `root:wheel` with mode `0644` (launchd refuses a daemon property list that anyone else can write), and loads it into the `system` domain (`launchctl bootstrap system <plist>`). A daemon runs when the Mac starts, whether or not anyone has logged in, so the profile and the node's container come back after a power loss with the Mac sitting at the login window. The daemon runs the same command with the same `PATH` and `COLIMA_HOME` as the agent does, as the connecting user (`UserName`, which launchd honours only for a job loaded into the system domain, and ignores for an agent: `man launchd.plist` on a Mac), with that user's `HOME` set in its environment, because launchd.plist(5) does not promise one for a daemon and Colima and Lima are Go programs, whose `os.UserHomeDir` is `$HOME` on macOS. Its log is in the user's `~/Library/Logs`, as the agent's is. Writing the property list and loading it take root, so the role uses `become` for these tasks and nothing else in the runtime tasks: run the play with passwordless sudo for the connecting user (the `github_runner_macos_host` role's `github_runner_macos_host_sudoers_nopasswd` grants it) or with `--ask-become-pass`. Colima's network helper (`socket_vmnet`) and its sudoers entry are the user's, installed the first time a profile with an address starts, and the daemon runs as the same user, so it needs nothing the agent did not.
157157

158158
A host that got the agent from release 2.19.0 moves over on its next run: the role unloads the node profile's agent from the user's login session when there is one, deletes its property list (also when nobody has logged in, so it cannot load at the next login and start the profile a second time) and loads the daemon. Unloading either kind does not stop the VM, which the job started detached, and loading one runs `colima start`, which does nothing to a running profile. A rerun with nothing changed makes no `launchctl` call that changes anything. With `github_runner_cluster_runtime_autostart` off the role installs, loads and removes none of this.
159159

‎tests/unit/test_runtime_autostart.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -236,7 +236,7 @@ def test_the_login_agent_names_no_user_and_sets_no_home(self) -> None:
236236
self.assertNotIn("HOME", self.plist["EnvironmentVariables"])
237237

238238
def test_the_node_profile_gets_a_daemon_that_runs_as_the_connecting_user_with_its_home(self) -> None:
239-
# Root's daemon would start the VM as root in /var/root; UserName makes it the user's, and a daemon is not given the user's HOME, which colima reads for its default home and for the Lima instance directory.
239+
# A daemon is root's unless UserName says otherwise, which would start the VM as root; HOME is set because launchd.plist(5) does not promise one for a daemon and colima and lima take their home directory (the default COLIMA_HOME and the Lima instance directory) from $HOME.
240240
plist = plistlib.loads(render_plist(docker_context="colima-node", github_runner_cluster_runtime_colima_home="/Users/example/.colima-node"))
241241
self.assertEqual(plist["Label"], "com.exadev.github-runner.colima.node")
242242
self.assertEqual(plist["UserName"], "example")

0 commit comments

Comments
 (0)