Share via

Geek of all Trades Setting Permissions from the Command Line

Greg Shields


Very Many Cacls
Managing Permissions over Time
Envisioning Permissions

An old friend and fellow IT professional has this pointed saying I find myself repeating a lot lately. It relates to how you go about accomplishing the tasks in your daily job—and your career. He says with finger in the air, "IT professionals who don't learn to complete their tasks from the command line won't be IT professionals in the next five years."


Figure 1 A Sample File Server Folder Structure

Now that's a dramatic statement, but it is one every IT professional should pay attention to. No matter whether you're a jack-of-all-trades or you dig deep into a specific focus, getting your hands off that mouse and onto the keyboard is arguably the number one skill you must master if you're to be successful in the coming years. Why the command line? Simply put: efficiency, repeatability, and assurance.

If you manage a technology through its GUI, any action accomplished there effectively evaporates once completed. You just can't reuse mouse clicks. In contrast, completing that action through the command line—whether via a command or a script—enables you to reuse your work over and over.

Nowhere is this more evident than with setting and managing Windows file system permissions, a task we do all the time. We set perms on files and folders. We update and manage our share permissions. From time to time, we might even update object permissions in the registry. All of these are actions that can be accomplished through the explorer or regedit graphical interfaces. But using those interfaces is cumbersome, prone to error, and hard on your wrists. If you've ever gotten most of the way through a long permissions change, only to have it crash on you somewhere in the middle with "Access is Denied," you know this pain.

Permissions modifications through the GUI are particularly problematic due to the sheer number of actors in play. Your small environment may have thousands of individual folders and hundreds of users, any of which can have multiple permissions assigned. Managing the enormous number of potential configurations that can result is no easy task. And if you share the workload with more than one administrator, you can be assured that things will change the very second you finally perfect the perms on a complex folder structure.

The way around these problems is to commit yourself to managing file system permissions from the command line. By taking your hand off the mouse and investing some effort in familiarizing yourself with a couple of tools, you'll be rewarded with a more efficient solution that is infinitely repeatable with complete assurance of success.

Very Many Cacls

The first tool we'll look at is "change access control lists," or cacls, a command line tool that has had a long and fruitful history with the Windows operating system. The original cacls shipped with Windows NT 4.0 and enabled a set of basic capabilities for changing permissions at the command line but was limited in what it could accomplish. To resolve these limitations, Microsoft subsequently released an expanded xcacls in the Windows NT Resource Kit. Later yet, an unsupported xcacls.vbs was released that went further with capability but backward in terms of performance.

The most recent and fully featured version, icacls, ships with Windows Vista and Windows Server 2008 and can be downloaded for Windows XP and Windows Server 2003 at Icacls includes much of the added functionality found in the experimental VBScript but arrives as a dramatically faster EXE. Icacls also adds support for managing Windows Integrity Levels, a secondary layer of access control we won't cover in this article.

Let's assume you are responsible for managing permissions on a file server with a folder structure resembling the one in Figure 1. There you'll see a root folder named Shared that contains the Finance and Marketing subfolders, which contains additional subfolders. You'll also notice that the folders are configured so that increasingly smaller groups of people can access lower-level shares. For example, Finance Users can read information in the Budget folder, but only Budget Users can write to it. A restricted folder is also present at the bottom that no one should be able to see except those with Restricted access. This is a common structure on many file servers today.

You can use icacls to set permissions like those in Figure 1, but exactly how to do this is not immediately obvious. To set the indicated permissions for just the Metrics folder, you would use the following syntax:

icacls C:\Shared\Finance\Metrics /grant:r "Finance Users":(OI)(CI)M /grant:r "Metrics Users":(OI)(CI)M

Unfortunately, with great power comes great complexity. As you can see, icacls' syntax can be quite impenetrable, at least until you understand how Windows permissions work. Remember that an individual permission can be applied to a single folder object or to the object plus its subfolders and files. This is the concept of inheritance. When you apply the simple Modify permission within the explorer GUI to a folder, as in Figure 2, you are actually applying it to that folder as well as all subfolders and files.


Figure 2 Applying Simple Permissions Automatically Sets Inheritance for Subfolders and Files.

In the command line above, you can see that for each group, the M for modify comes after (OI)(CI), which stand for "object inherit" and "container inherit" respectively. Both of these are necessary if you want icacls to apply the simple modify permission. You'll also notice that ":r" is added after the /grant switch. This modifier instructs icacls to clear any directly applied permissions on the object before adding the permissions you set in the command line.

Complex, yes, but Windows permissions are complex. Keep in mind that the end goal—reusable commands—will actually make things much simpler.

To continue the example, let's walk through the entire set of icacls command lines you would use to reset and correctly apply the stated permissions to the Finance folder structure as well as its root:

Icacls C:\Shared /inheritance:r /grant:r "Domain Users":(OI)(CI)R /grant:r 
   "File Admins":(OI)(CI)F

Icacls C:\Shared\Finance /inheritance:r /grant:r "Finance Users":(OI)(CI)R /grant:r 
   "File Admins":(OI)(CI)F

Icacls C:\Shared\Finance\Budget /grant:r "Budget Users":(OI)(CI)M
Icacls C:\Shared\Finance\Metrics /grant:r "Metrics Users":(OI)(CI)M

The first line actually accomplishes two tasks. It starts with the "/inheritance:r" switch to completely remove all inherited permissions from the folder above so that the Shared folder doesn't inherit. This breaks the Shared folder's inheritance from the folder immediately above it. Once this is done, the Read permission for is set for Domain Users and the Full Control permission for File Admins.

Because we don't want Domain Users to have access to the Finance folder at all, line two breaks and clears the permissions inheritance once again. It then applies the Full Control permission to File Admins and the Read permission to Finance Users.

With lines three and four, we don't want to break the permissions inheritance because both the File Admins and the Finance Users groups should have the same access to these subfolders. In these two lines, we are simply granting another permission—in addition to the existing inherited permissions—so that the Budget Users and Metrics Users can write to these folders.

Setting permissions for the Marketing folder is slightly different. We use the same permissions flow for the Product folder as we did for the subfolders under Finance, but the Restricted folder will be treated a bit differently. Let's suppose that folder contains highly secret documents that should be seen by only a very few individuals. Your first thought may be, "A-ha! Here, I'll use the Deny permissions to prevent the wrong users from accessing this folder!"

But keep in mind that the Deny permissions is actually far too powerful a setting for most situations as it automatically overrides every other permission. Therefore, adding the Deny permission to the Marketing Users group for this folder means that any Restricted users who are also Marketing users would be shut out. A more appropriate solution here is to break the inheritance again and simply eliminate all permissions for the Marketing Users group. Thus, the three icacls command lines required to set the permissions for this structure are

Icacls C:\Shared\Marketing /inheritance:r /grant:r 
  "Finance Users":(OI)(CI)R /grant:r "File Admins":(OI)(CI)F

Icacls C:\Shared\Marketing\Product /grant:r "Product Users":(OI)(CI)M

Icacls C:\Shared\Marketing\Restricted /inheritance:r /grant:r 
   "File Admins":(OI)(CI)F /grant:r "Restricted Users":(OI)(CI)M

Managing Permissions over Time

So it takes seven lines at the command prompt to set permissions on this simple folder structure. That seems like a lot of work to accomplish relatively little, but consider your IT environment and how things change over time. How many times have you configured a folder structure, only to have some inexperienced fellow administrator make changes while you're away? How many times has your help desk responded to a phone call by blindly modifying your exquisitely designed permissions structure at the whim of a user? These are common problems that are particularly challenging if your environment has too many people with too much access. If you use the mouse and the Windows GUI to keep all these folders straight, you're in for long evenings tracking down changes.

Let me offer you a much better solution. If you spend the extra time up front coding your permissions structure into a command line tool like icacls, reapplying that structure involves little more than double-clicking a batch file. Once you've authored lines like the seven above, keep them around for later use. You'll find that it becomes trivial to revert your permissions structure back to its intended state by simply invoking those lines again.

If built-in automation is more your style, icacls also lets you store and reapply permissions. Once you've applied your equivalent of the seven lines above, run this command:

icacls C:\Shared /save {fileName} /T

Icacls will analyze the permissions structure for C:\Shared and create the file identified in {fileName}. As you can see in Figure 3, the contents of this file are in a binary format and, as a result, the file should not be opened in a text editor like Notepad. However, you can use this file as is to reapply those permissions at a later time. The command syntax to reapply the permissions to the same folder is


Figure 3 Icacls’ Save Function Creates a File that can Reapply Permissions at a Later Time.

icacls C:\Shared /restore {fileName} 

With this, you have an easy-to-deploy solution for fixing permissions when they've deviated from your original design.

Envisioning Permissions

As you've seen, icacls is very useful for setting and managing permissions. What it is not so great at is allowing you to see your permissions structure. If you've found yourself walking down the folder tree, right-clicking each folder and choosing Properties to check each object's Security tab, you know what a pain that is. Icacls does have a mechanism for viewing permissions, but its tool is text-based and not entirely useful. If you run the command

icacls C:\Shared /t

icacls will list the permissions on each object in your entire folder structure; however, watching screenfuls of text fly by is no way to find a broken perm.

A far better idea is to download the free AccessEnum tool. AccessEnum is a very simple application that helps you visualize the permissions assigned to a specific folder structure. Specifically, when you target AccessEnum to a top-level folder in a folder tree, the tool scans the files and folders beneath and reports back where permissions are different from the parent.

This difference-based view of permissions helps you find where permissions have been misconfigured. It works because of the natural way in which permissions are set in a folder structure. If you look back at Figure 1, you'll see how well-designed Read permissions typically flow down from the top level. Modify permissions are set at specific levels down the structure as users change from readers to contributors. AccessEnum's difference-based view supports this by hiding permissions that don't change and exposing only those that do. Figure 4 shows an example of how AccessEnum's view might look when applied to this column's sample folder structure.


Figure 4 AccessEnum Helps with Visualizing Your Permissions Structure.

The net result of using icacls and AccessEnum should be a more cohesive application of permissions within your file servers. A further result will be a greater level of data security, as you will be assured your users can access only the files and folders that make sense for them.

This short description only touches the surface of Windows permissions and how they can be applied. Through tools like icacls, you can set permissions that apply to only one folder with no inheritance to the folders below, useful where you want to allow access at a single layer only. You can set integrity levels for data that requires special handling no matter what discretionary controls you apply to it. You can even search for files and permissions across entire structures when necessary. So get your hands off that mouse and start architecting permissions from the command line.

Greg Shields, MVP, is a partner at Concentrated Technology. Get more of Greg's Jack-of-all-Trades tips and tricks at