From 5d0505da688ffe769101c7666a8afbfb57c551a5 Mon Sep 17 00:00:00 2001 From: coreybutler <770982+coreybutler@users.noreply.github.com> Date: Mon, 16 Nov 2026 15:26:54 -0600 Subject: [PATCH] docs: document RequireActivationSymlinks for OpenSSH Explain certified policy for symlink activation links when Windows OpenSSH Redirection Guard blocks non-admin junctions (nvm#1564). Signed-off-by: Corey Butler <770982+coreybutler@users.noreply.github.com> --- docs/_components/SymlinkPermissionExplainer.mdx | 4 ++-- docs/features/modes.md | 10 ++++++++++ 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/_components/SymlinkPermissionExplainer.mdx b/docs/_components/SymlinkPermissionExplainer.mdx index 93537e7..870c8ab 100644 --- a/docs/_components/SymlinkPermissionExplainer.mdx +++ b/docs/_components/SymlinkPermissionExplainer.mdx @@ -1,9 +1,9 @@ -[Link mode](/features/modes#link-mode) uses an NTFS junction to select the Node.js version. +[Link mode](/features/modes#link-mode) uses an NTFS junction or a symbolic link to select the Node.js version. See also [activation links and OpenSSH](/features/modes#activation-symlinks). - NTFS junctions do not need a special privilege. - NTFS junctions do not support UNC paths such as a network share or a mapped drive. -If Node.js storage uses a UNC path, NVM for Windows creates a symbolic link. +If Node.js storage uses a UNC path, or Certified Builds enable `RequireActivationSymlinks`, NVM for Windows creates a symbolic link. Windows requires the `SeCreateSymbolicLinkPrivilege` privilege to create that symbolic link. :::tip[Enable `SeCreateSymbolicLinkPrivilege`] diff --git a/docs/features/modes.md b/docs/features/modes.md index 261ab72..323366f 100644 --- a/docs/features/modes.md +++ b/docs/features/modes.md @@ -41,6 +41,16 @@ flowchart LR NVM for Windows v2 will not attempt to elevate permissions (i.e. no UAC prompt) on failure of symlink creation. If permissions block the creation of a link, a native desktop notification warns users and offers guidance. ::: +## Activation links and OpenSSH \{#activation-symlinks\} + +`PATH` always contains the `.nodejs` activation entry. By default, NVM for Windows creates that entry as an NTFS junction (shim mode: `.nodejs` → `.shim`; link mode: `.nodejs` → `.link\nodejs`, and `.link\nodejs` → the active version). + +Windows OpenSSH can enable Redirection Guard on `sshd`. That mitigation blocks traversal of junctions that a non-administrator created. Local terminals still work. SSH sessions may report that `.nodejs` is an untrusted mount point and fail to find `node`. + +**Certified Builds** can set machine policy `RequireActivationSymlinks` (registry `RequireActivationSymlinks`). When enabled, activation links are created as symbolic links only. Pair the policy with Developer Mode or `SeCreateSymbolicLinkPrivilege` from Group Policy so creation does not fail. After you enable the policy, the next `nvm on`, mode switch, profile init, or link-mode `nvm use` recreates existing junctions as symlinks. + +Community Builds keep the default junction-first behavior unless an administrator sets the same registry value manually. + ## Shim Mode (default) \{#shim-mode-default\} Shim mode offers a new, streamlined developer experience. When compared with Link Mode, Shim Mode comes with the benefit of avoiding esoteric permission requirements, but at the cost of a small amount of additional latency (~25-35ms total). This latency is negligible for most use cases. For this reason, Shim Mode is recommended for most users.