Node.js Reference ยท process
Node.js process.getuid() and related methods
Reference for process.getuid(), geteuid(), getgid(), getegid(), getgroups() and the setters in Node.js: reading user and group identity and dropping privileges.
On POSIX systems every process runs as a user and a group. Node.js exposes those identities through a family of methods on process: getuid() and geteuid() for the real and effective user ID, getgid() and getegid() for the group IDs, and getgroups() for the supplementary groups. Matching setters (setuid(), setgid() and others) change them.
These functions only exist on POSIX platforms (Linux, macOS and the BSDs). On Windows they are undefined, so code that must run everywhere should check for them first. The IDs matter mainly for servers that start as root to open a privileged port and then drop to an ordinary account.
if (process.getuid) { console.log(process.getuid(), process.getgid()); }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
process.getuid(): number process.geteuid(): number process.getgid(): number process.getegid(): number process.getgroups(): number[] process.setuid(id: number | string): void process.seteuid(id: number | string): void process.setgid(id: number | string): void process.setegid(id: number | string): void process.setgroups(groups: Array<number | string>): void process.initgroups(user: number | string, extraGroup: number | string): void
| Name | Description |
|---|---|
id |
A numeric ID, or a user or group name that Node looks up in the system database. |
groups |
An array of numeric group IDs or names. |
user |
A user name or ID whose group list is loaded. |
extraGroup |
One more group added to that list. |
Returns: the getters return integers (getgroups() returns an array). The setters return nothing.
Errors / edge cases: a setter throws with code EPERM when the process lacks the privilege, or ERR_UNKNOWN_CREDENTIAL when a name does not exist. In a worker thread the setters throw ERR_WORKER_UNSUPPORTED_OPERATION.
Usage notes
- Real versus effective. The effective ID decides permission checks; the real ID records who started the process. They differ for set-user-ID programs.
- Drop privileges in the right order: call
initgroups()orsetgroups()first, thensetgid(), andsetuid()last. Aftersetuid()to an unprivileged user a process cannot get root back, which is exactly the point. - Do not run servers as root. Start as root only to bind port 80 or 443, then drop. Containers usually do better with a non-root user from the start.
- Feature-detect on Windows, for example with
process.getuid?.(), or the code throws aTypeErrorwhen called. - Names or numbers. Passing a name costs a lookup in the account database; numbers are faster and unambiguous.
- Files are affected too: newly created files are owned by the effective user and by the effective group. See also
process.umask(). - Not a security boundary on its own. Dropping privileges limits damage after a bug, but it does not isolate memory or the file system. Combine it with containers and least-privilege file permissions.