Symbolic Links Quick Reference

From TNG_Wiki
Jump to navigation Jump to search


Drop a.jpg

symbolic link, also termed a soft link, is a special kind of file or folder that points to another file or folder, much like a shortcut in Windows or a Macintosh alias. Unlike a hard link, a symbolic link does not contain the data in the target file. It simply points to another entry somewhere in the file system.

This reference only deals with folder symbolic links like a 'photos' folder link that, when you open it, appears to contain all the directories and files of the real target folder somewhere else on the system. And changes made here are reflected in the real folder. The icon for a folder symbolic link looks like a folder with a little arrow on it.


How Folder Symbolic Links Work

A normal directory listing for a file or folder points to a discrete area of the hard drive where it's data is stored. A symbolic link also points to the same area of the hard drive, so no matter how many symbolic links point to it, there is only one copy of the target files.

The big difference between them is this: if you delete a symbolic link, only the link is removed. If you delete a normal directory listing the listing and all of it's content are removed.

Folder symbolic links pointing to the same media files do have the advantage of saving disk space, but the biggest benefit is that one can add to, and maintain media files in one place and the updates will appear everywhere. For example, you could have a dozen version-specific TNG test sites, each with Symlinks pointing to the same media files. Maintaining and backing up multiple collections of the same media files is difficult at best.

Important: This will be obvious to some, but still bears repeating. For those who would consolidate all their media folders under a master folder like exhibits, both in the master location and in several TNG sub-directory installations, there only needs to be a single folder symbolic link -- exhibits -- in the TNG directory which points to the master folder. With that one link, all the real folders and files in the master folder will be available in the TNG directory just as if all the content were still there. On the other hand, if one moves each media folder (photos, documents, etc.) to separate master locations within the site, then they will need a folder symbolic link in the TNG site for each one of them.



Document Root is the highest level folder in the file hierarchy that can be accessed on the server via a browser. It will usually be the public_html (sometimes named www) folder. In other words this folder and all its subfolders are web accessible.
TNG Root is the folder containing a TNG website -- it may or may not be the same as the Document Root. If not, it will be a subfolder of the document root.


It is important to understand that symlinks for images will not work with folders above the Server's Document Root. The reason is that, while PHP is allowed to operate above the document root, the html code that displays images is not. For security reasons the server will not allow html to follow symlinks pointing to the private area above the document root.

To use a common folder for photos, for example, we could have a master photos folder and several TNG sites with symbolic links under www (public_html) like this:

www/tng1112/photos (symlink)
www/tng1200/photos (symlink)
www/tng1201/photos (symlink)

Using the symbolic link, the TNG database will find all the photos in the master location (www/photos) as if they were local.

Navigating a browser to will display mydad.jpg as if it were actually present in the tng1200 website.

How to Create Them

Below we provide the syntax or code for creating a folder symbolic link on Windows 10, Linux and on your shared hosting website.

Windows 10 Command Line

  • Type cmd in the search box.
  • Right-click on Command Prompt
  • Select Run as administrator.
  • Navigate to directory where you want to create the symbolic link.


mklink /D link_name real_target_folder

/D creates a directory symbolic link named "link_name" in the current directory. It will point the "real_target_folder".


D:\documents> mklink /D symlink_folder "..\real_folder"

  • Note the quotes around the target path.
  • We are in the directory (documents) where we want to place the symbolic link.
  • We use the command mklink /D so we will be creating a directory symbolic link.
  • symlink_folder is the name of the directory symbolic link to create.
  • ../real_folder is the target folder whose contents will appear when you open symlink_folder.

Linux Terminal Command Line

Open a console window and navigate to the folder where the directory link is to be created.


ln -s -d target symlink_name (command is lower case LN)

note: this is opposite to the arguments in windows mklink where the symlink_name comes first

-s creates symbolic link as opposed to hard link -d creates a directory link (a file link is default)


To create a folder -- exhibits -- in current directory pointing to a real folder of the same name above the document root:

ln -s -d /home/rick/bfam/exhibits exhibits

Shared Hosting Website

Use the following as a guide. Create a php script to add the symlink(s). Adjust the absolute server paths in the example below to conform to your own site. Some sites will use www instead of public_html and some that use public_html will also provide a www symbolic link pointing to public_html. Use whatever works. Change $target and $symlink to suit your needs.

NB. The real folder cannot exist for the symbolic link to work. So if you used a full install to create a new test sandbox you will need to delete the folders for which you want symbolic links to point to your production web site to work. Note also that user as shown below is your user account on your hosting service.

/* The symlink() function creates a symbolic link from the existing target with the specified name link.

This function returns TRUE on success, or FALSE on failure.

$target should be the absolute path to where the files exist 
$symlink should be the absolute path to which you want to create a symbolic link 

NB  if the real folder exists, you need to delete it for the symbolic link to work */

$target = '/home/user/public_html/photos';
$symlink = '/home/user/public_html/tng12/photos';
symlink( $target, $symlink );
if( !symlink ) {
    echo "Cannot create target $symlink link to $target <br />";
else {
    echo "Symbolic link for $symlink created to $target !<br />";

Please note, when you create a php file to make the links for you, it must be executed on your website. If the php filename is 'makelink.php', then you must upload it to your website, say to the TNG root, then navigate your browser to the the root and execute the file. Examples:
. After the script is run successfully, you should delete it from a live website to prevent a mischief maker running it.

Related Links