# NTFS links

NTFS links are the abstraction used in the NTFS file system—the default file system for all Microsoft Windows versions belonging to the Windows NT family—to associate pathnames and certain kinds of metadata, with entries in the NTFS Master File Table (MFT). NTFS broadly adopts a pattern akin to typical Unix file systems in the way it stores and references file data and metadata; the most significant difference is that in NTFS, the MFT "takes the place of" inodes, fulfilling most of the functions which inodes fulfill in a typical Unix filesystem.
In NTFS, an entity in the filesystem fundamentally exists as: a record stored in the MFT of an NTFS volume, the MFT being the core database of the NTFS filesystem; and, any attributes and NTFS streams associated with said record. A link in NTFS is itself a record, stored in the MFT, which "points" to another MFT record: the target of the link. Links are the file "entries" in the volume's hierarchical file tree: an NTFS pathname such as \foo.exe or \foobar\baz.txt is a link. If the volume containing said pathnames were mapped to D: in a Windows system, these could be referenced as D:\foo.exe and D:\foobar\baz.txt. (Compare and contrast with typical Unix file systems, where a link is an entry in a directory—directories themselves being just a type of file stored in the filesystem—pointing either to another link, or to an inode.)

## Types of links

NTFS has four types of links. These map relatively closely to the generic hard link and soft link concepts which modern file systems tend to follow.

### Hard links

Hard links are typical in behavior. A hard link "points" to an MFT record. That target record will be the record for a "regular" file, such as a text file or executable (assuming the NTFS volume is in a normal "healthy" state). Compare with a typical Unix file system, where a hard link points to an inode. As in such file systems, an NTFS hard link cannot point to a directory.
A typical new file creation event on an NTFS volume, then, simply involves NTFS allocating and creating one new MFT record, for storing the new file entity's file metadata—including, about any of the data clusters assigned to the file, and the file's data streams; one MFT record for a hard link which points to the first newly-created MFT record as its target; storing a reference to the hard link in a directory file; and setting the reference count of both these MFT records to 1. Any file name provided as part of the file creation event is stored in the hard link. An MFT record can be the target of up to 1024 hard links; each time a new hard link is successfully created, targeting a previously extant MFT record, the target's reference count is incremented.
Symmetrically, the immediate tasks performed by NTFS in a typical file deletion event, when deleting a hard link, are simply: removing the reference to the link from the directory file containing it (the root directory, if applicable); and decrementing by 1 the reference counts of the MFT record targeted by the link, and, of the entry containing the hard link itself. Any MFT record which now has a refcount of 0, is now in the "deleted" state: all its associated resources are considered "free" by NTFS, to be freely overwritten and used as needed.

### Junction points

Junction points are NTFS reparse points and operate similarly to symbolic links in Unix or Linux, but are only defined for directories, and may only be absolute paths on local filesystems (as opposed to remote filesystems being accessed). They are created and behave in a similar way to hard links, except that if the target directory is renamed, moved, or deleted, the link will no longer be valid.

### Symbolic links

Symbolic links are reparse points which operate similarly to Junction Points, or symbolic links in Unix or Linux, and accept relative paths and paths to files as well as directories. Support for directory and UNC paths were added in NTFS 3.1.
* NTFS volume mount points
All NTFS links are intended to be transparent to applications. This means that the application accessing a link will be seamlessly redirected by the file system driver, and no special handling is needed. To users, they appear as normal directories or files. This also leads to an aliasing effect: writes to a link will pass the write to the underlying, linked file or MFT entry.
Symbolic links and junction points contain the path to the linked file, and a tag identifying the driver which implements the behaviour. Because they record the path, they can link to files on other volumes or even remote files. However this also means that if the referenced file is deleted or renamed, the link becomes invalid, and if the referenced file or directory is replaced with another, the link will now refer to the new file or directory.

### Shortcut files

An NTFS symbolic link is not the same as a Windows shortcut file, which is a regular file. The latter may be created on any filesystem (such as the earlier FAT32), may contain metadata (such as an icon to display when the shortcut is viewed in Remove links), and is not transparent to applications.
Implementations of unix-like environments for Windows such as Cygwin and Mingw can use shortcut files to emulate symbolic links where the host operating system does not support them, if configured to do so.

## Examples of use
### Built-in uses

* Windows Component Store (WinSxS) use hard links to keep track of different versions of DLLs stored on the hard disk drive.
* Basic installations of Windows Server 2008 used symlinks for \Users\All Users\ → \ProgramData\ redirection.
* Since Windows Vista, all versions of Windows have used a specific scheme of built-in directories and utilize hidden junctions to maintain backward compatibility with Windows XP and older. Examples of these junctions are:
** C:\Documents and Settings pointing to C:\Users
** %USERPROFILE%\Application Data pointing to %USERPROFILE%\AppData\Roaming
** %USERPROFILE%\My Documents\My Pictures pointing to %USERPROFILE%\Pictures

### Program redirection

By setting a junction point that points to a directory containing a particular version of a piece of software, it may be possible to add another version of the software and redirect the junction point to point to the version desired.

### Saving storage space

The contents of a junction use almost no storage space (they simply point to the original directory). If an administrator needs to have multiple points of entry to a large directory, junction points can be an effective solution. Junction points should not be confused with a copy of something as junctions simply point to the original. If directories need to be modified separately a junction cannot be used as it does not provide a distinct copy of the directory or files within.
Likewise, symbolic links and hard links are useful for merging the contents of individual files.

### Circumventing predefined paths

Since reinstalling Windows (or installing a new version) often requires deleting the contents of the C: drive, it is advantageous to create multiple partitions so only one partition needs to be deleted during the installation. However, some programs don't let the user choose the installation directory, or install some of their files to the C: drive even when they are installed to a different drive. By creating a junction point, the program can be tricked into installing to a different directory.

## Command-line tools

Windows comes with several tools capable of creating and manipulating NTFS links.
* PowerShell: The New-Item cmdlet of Windows PowerShell that can create empty files, folders, junctions, and hard links. In PowerShell 5.0 and later, it can create symbolic links as well. The Get-Item and Get-ChildItem cmdlets can be used to interrogate file system objects, and if they are NTFS links, find information about them. The Remove-Item cmdlet can remove said items, although there has been a record of a bug preventing this cmdlet from working properly.
* Windows Command Prompt: Starting with Windows Vista and Windows Server 2008, the mklink internal command can create junctions, hard links, and symbolic links. This command is also available in ReactOS. In addition, the venerable dir command can display and filter junction points via the /aL switch. Finally, the rd command (also known as rmdir) can delete junction points.
* fsutil.exe: A command-line utility introduced with Windows 2000. Its hardlink sub-command can make hard links or list hard links associated with a file. Another sub-command, reparsepoint, can query or delete reparse points, the file system objects that make up junction points, hard links, and symbolic links.
In addition, the following utilities can create NTFS links, even though they don't come with Windows.
* linkd: It is a component of the Resource Kit for Windows 2000 and Windows Server 2003. It can make junction points.
* junction: A free command-line utility from Microsoft, it can create or delete junctions.
* PowerShell Community Extensions (PSCX): Hosted on Microsoft PowerShell Gallery, this module adds several cmdlets for dealing with NTFS links, including: New-Hardlink, New-Junction, Get-ReparsePoint, Remove-ReparsePoint, and New-Symlink.

## APIs

To create hard links, apps may use the CreateHardLink function of Windows API. All versions of the Windows NT family can use GetFileInformationByHandle to determine the number of hard links associated with a file. There can be up to 1024 links associated with an MFT entry. Similarly, the CreateSymbolicLink function can create symbolic links. Junctions are more complex to create. They require manual reparse point information filling. A code example is found in libuv. Junctions are defined for directories only: although the API does not fail when one creates a junction pointing to a file, the junction will not be interpreted successfully when used later.
Junctions and symbolic links, even those pointing to directories, can be removed with pNtSetInformationFile. Libuv's implementation of unlink on Windows demonstrates this use. Alternatively, the .NET System.IO.Directory.Delete method works on them as well.

## Hazards
### Consistency

Symbolic links and NTFS junctions can point to non-existent targets because the operating system does not continuously ensure that the target exists.
Additional hazards lurk in the use of NTFS directory junctions that:
* include links that refer to their own parent folders, such as creating hard link X:\path\to\parent which points to either X:\path\ or X:\path\to\, or
* specify targets by using volume drive letters, such as X:, in X:\some\path\.

### Recursive structure

The problem in the first case is that it creates recursive paths, which further implies infinite recursion in the directory structure. By introducing reentrancy, the presence of one or more directory junctions changes the structure of the file system from a simple proper tree into a directed graph, but recursive linking further complicates the graph-theoretical character from acyclic to cyclic. Since the same files and directories can now be encountered through multiple paths, applications which traverse reentrant or recursive structures naively may give incorrect or incoherent results, or may never terminate. Worse, if recursively deleting, such programs may attempt to delete a parent of the directory it is currently traversing.
Note that both of the conditions listed above exist in the system of hard links established on the C: drive in the default Windows setup. For example, every Windows 10 installation defines the recursive path:
Each additional path name in this seemingly infinite set is an actual valid Windows path which refers to the same location. In practice, path names are limited by the 260-character DOS path limit (or newer 32,767 character limit), but truncation may result in incomplete or invalid path and file names. Whenever a copy of a Windows installation is archived, with directory junctions intact, to another volume on the same—or worse—another computer, the archived copy may still incorporate active folders from the running installation. For example, depending on the method used for copying, a backup copy of a Windows drive X:\archive\... will include a hard link called X:\archive\Users\USERNAME\My Documents which still points to folder C:\Users\USERNAME\Documents\ in the current, active installation.

### Cross-volume traversal

The second form of deferred target mis-referral, while conceptually simpler, can have more severe consequences. When a self-consistent volume or directory structure containing hard links which use volume drive-letter path names is copied or moved to another volume (or when the drive letter of a volume is reassigned by some other means), such links may no longer point to the corresponding target in the copied structure. Again the results depend on the software that was used for copying; while some programs may intercede by modifying any fully subsumed hard links in the copy in order to preserve structural consistency, others may ignore, copy exactly, or even traverse into hard links, copying their contents.
The serious problems occur if hard links are copied exactly such that they become, in the new copy, cross-volume hard links which still point to original files and folders on the source volume. Unintentional cross-volume hard links, such as hard links in an "archive" folder which still point to locations on the original volume (according to drive letter), are catastrophes waiting to happen. For example, deleting what is much later presumed to be an unused archive directory on a disused backup volume may result in deleting current, active user data or system files.
A preventative measure for the drive-letter hazard is to use volume GUID path syntax, rather than paths containing volume drive letters, when specifying the target path for a directory junction. For example, consider creating an alias for X:\Some\Other\Path at X:\Some\Path\Foo:
X:\Some\Path> linkd Foo X:\Some\Other\Path
As described above, if the folder structure that contains the resulting link is moved to a disk with a drive letter other than X:, or if the letter is changed on drive X: itself, the data content at the target location is vulnerable to accidental corruption or malicious abuse. A more resilient version of this link can partially mitigate this risk by referencing the target volume by its GUID identifier value (which can be discovered by running the fsutil volume list command).
X:\Some\Path> linkd Foo \\?\Volume{12345678-abcd-1234--abcdefghijkl}\Some\Other\Path
Doing so ensures that the junction will remain valid if drive letter X: is changed by any means.
As for a proactive means of avoiding directory junction disasters, the command dir /AL /S /B "X:\Some\Path" can be used to obtain, for careful analysis prior to committing any irreversible file system alterations, a list of all hard links "below" a certain file system location. While by definition every link in the resulting list has a path name that starts with X:\Some\Path\, if any of those hard links contains a target which is not subsumed by X:\Some\Path, then the specified scope has been escaped, and the starting directory you specified is not fully-subsuming. Extra caution may be indicated in this case, since the specified directory includes files and directories which reside on other physical volumes, or whose own parent-traversal-to-root does not include the specified directory.

## Limitations
### Privilege requirements

The default security settings in Windows disallow non-elevated administrators and all non-administrators from creating symbolic links but not junctions. This behavior can be changed running "secpol.msc", the Local Security Policy management console (under: Security Settings\Local Policies\User Rights Assignment\Create symbolic links). It can be worked around by starting cmd.exe with Run as administrator option or the runas command. Starting with Windows 10 Insiders build 14972 the requirement for elevated administrator privileges was removed in Windows "Developer Mode", allowing symlinks to be created without needing to elevate the console as administrator. At the API level, a SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE flag is supplied for this purpose.

### Boot time

The Windows startup process does not support junction points, so it is impossible to redirect certain system folders:
* \Windows
* \Windows\System32
* \Windows\System32\Config
Other critical system boot files, such as The sleep image file hiberfil.sys, also do not support redirection.

### System-defined locations

It is technically possible to redirect the following non-critical system folder locations:
* \Users
* \Documents and Settings
* \ProgramData
* \Program Files
* \Program Files (x86)
Doing this may lead to long-term Windows reliability or compatibility issues. Creating junctions for \Users and \ProgramData pointing to another drive is not recommended as it breaks updates and Windows Store Apps.
Creating junctions for \Users, \ProgramData, \Program Files or \Program Files (x86) pointing to other locations breaks installation or upgrade of Windows.
Creating junctions for \Program Files or \Program Files (x86) pointing to another drive breaks Windows' Component Based Servicing which hardlinks files from its repository \Windows\SxS to their installation directory.

### Windows installer

Windows Installer does not fully support symbolic links. Redirecting \Windows\Installer will cause most .msi-based Windows installers to fail with error 2755 and/or error 1632.

### Symbolic link support in Windows XP

Since Windows XP uses the same NTFS format version as later releases, it's feasible to enable symbolic links support in it. For using NTFS symbolic links under Windows 2000 and XP, a third-party driver exists that does it by installing itself as a file system filter.

## History

Symbolic links to directories or volumes, called junction points and mount points, were introduced with NTFS 3.0 that shipped with Windows 2000. From NTFS 3.1 onwards, symbolic links can be created for any kind of file system object. NTFS 3.1 was introduced together with Windows XP, but the functionality was not made available (through ntfs.sys) to user mode applications. Third-party filter drivers – such as Masatoshi Kimura's opensource senable driver – could however be installed to make the feature available in user mode as well. The ntfs.sys released with Windows Vista made the functionality available to user mode applications by default.
Since NTFS 3.1, a symbolic link can also point to a file or remote SMB network path. While NTFS junction points support only absolute paths on local drives, the NTFS symbolic links allow linking using relative paths. Additionally, the NTFS symbolic link implementation provides full support for cross-filesystem links. However, the functionality enabling cross-host symbolic links requires that the remote system also support them, which effectively limits their support to Windows Vista and later Windows operating systems.