akkudoktoreos.server.server.drop_root_privileges

akkudoktoreos.server.server.drop_root_privileges(run_as_user: str | None = None) → bool

Drop root privileges and switch execution to a less privileged user.

This function transitions the running process from root (UID 0) to the specified unprivileged user. It sets UID, GID, supplementary groups, and updates environment variables to reflect the new user context.

If the process is not running as root, no privilege changes are made.

Parameters:

run_as_user (str | None) – The name of the target user to switch to. If None (default), the current effective user is used and no privilege change is attempted.

Returns:

True if privileges were successfully dropped OR the process is already running as the target user. False if privilege dropping failed.

Return type:

bool

Notes

• This must be called very early during startup, before opening files, creating sockets, or starting threads.

• Dropping privileges is irreversible within the same process.

• The target user must exist inside the container (valid entry in /etc/passwd and /etc/group).