Symbolic Links Quick Reference

From TNG_Wiki
Jump to navigation Jump to search

Introduction

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.

Ss001.png

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 the TNG root, there only needs to be a single folder symbolic link -- exhibits -- in the TNG root which points to the master folder. With that one link, all the real folders and files in the remote folder will be available in the TNG root just as if all the content were still in the root. On the other hand, if one moves each media folder (photos, documents, etc.) to separate master locations, then they will need a folder symbolic link in the TNG root for each one of them.

Restrictions

Definitions

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.

Images

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 outside the document root, the html code that displays images is not permitted for security reasong 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/photos
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 as if they were local.

Navigating a browser to www.example.com/tng1200/photos/mydad.jpg will display the photo 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.

Syntax

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".

Example

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.

Syntax

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)

Example

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

In this example we will create a directory symbolic link in the document root named symfolder and point it to a media folder located in the private area above the document root. You can place the media folder anywhere on your site that can be reached using an absolute path.

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 media and symfolder names to suit your needs.

<?php
$target = '/home/user/public_html/photos';
$symlink = '/home/user/public_html/tng12/photos';
if( !symlink( $target, $symlink ) {
    echo 'Cannot create link!';
    exit;
}
else {
    echo 'Symbolic link created!';
    exit;
}
?>

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:

https://myfamily.com/genealogy/makelink.php
localhost/tng1201/makelink.php
. After the script is run successfully, you should delete it from a live website to prevent a mischief maker running it.

Related Links