Information Store—Pfadmin’s Setacl Command

Tools for Exchange administrators

This new column, Information Store, offers details and tips about various Exchange Server tools in the Microsoft resource kits. (I'll concentrate mostly on Exchange Server 5.5 utilities, but I'll occasionally touch on Exchange 2000 Server tools as well.) To kick off the column, I want to introduce you to a few handy tools in the Microsoft BackOffice Resource Kit (BORK). These somewhat obscure but powerful utilities can help you manage your Exchange 5.x or 4.0 environment.

First on the list is Pfadmin, a command-line tool that helps you manage public folders. You can use Pfadmin to perform a variety of tasks, including changing permissions on folders, rehoming folders, replicating public folders across an enterprise, and listing the file types and number of files present in a public folder. These capabilities are particularly helpful when your environment contains several Exchange servers, has a large public store, or sustains a high employee turnover rate. (Exchange 2000 administrators: Don't feel left out. The Microsoft Exchange 2000 Server Resource Kit contains a version of the tool that works on Exchange 2000. For information about that version, see the Microsoft article "XADM: Exchange 2000 Public Folder Administration Tool" at http://support.microsoft.com/support/ kb/articles/q287/1/10.asp.)

First Things First
Earlier versions of Pfadmin (earlier than 1.2.1) are buggy, so be sure to install the tool from the BORK, Part III or the Exchange 5.5 CD-ROM. The Microsoft article "XADM: Pfadmin: Setacl Sets 'Default' User Role to None" (http://support.microsoft.com/support/ kb/articles/q182/9/62.asp) explains the problem that earlier versions can cause and how to determine whether you're using a faulty version.

Pfadmin doesn't have a Setup program; simply copy the necessary files to your server, and you're ready to go. (You can put the files anywhere on the server. For convenience, I put the files in the root of the C partition.) To install Pfadmin from the BORK 4.5 CD-ROM, open the platformexchangepftools directory (where platform is i386 or alpha) and copy pfadmin.exe and dapi.dll to your Exchange server. Then open the platformsetuplibs directory and copy mapi32.dll, mfc42.dll, msvcirt.dll, and msvcrt.dll to your Exchange server. To install Pfadmin from the Exchange 5.5 CD-ROM, copy pfadmin.exe from the CD-ROM's serversupportautorunreskitpf- admin directory and copy dapi.dll, mapi32.dll, mfc42.dll, msvcirt.dll, and msvcrt.dll from serversetupplatform. Be sure to put these files on the Exchange server. You can't run Pfadmin from a workstation.

Six Tools in One
Pfadmin includes six commands: Setacl, Rehome, Setreplicas, Listacl, Listreplicas, and Messageclasses. You can use the Setacl command to set permissions on public folders. Use Rehome to reset the public folders' home server to a different server. (If a public folder replica already exists, this command resets that replica. If no replica exists, the command creates one and sets the home instance.) Use Setreplicas to set public folders to replicate to other servers. Listacl lists permissions for public folder mailboxes, and List-replicas lists public folder replicas and the servers on which they reside. You can use the Messageclasses command to search a specified folder tree, examine the message classes of every message, then write a Comma Separated Value (CSV) file that contains one line for each examined folder.

You can use several switches in conjunction with the Pfadmin commands. The /cn switch sets the console logging level, the /dn switch sets the debug file logging level, the /en switch sets the Windows NT Event Viewer logging level, and the /ln switch sets logging to the same level for all three. The available levels are 0 (none), 1 (status), 2 (error), 3 (warning), 4 (info), or 5 (debug).

Pfadmin also provides Help files. To access general Help for the tool, open a command prompt, then type

pfadmin /?

To export the file for easy reference, type

pfadmin /? > c:pfadminhelp.txt

For additional Help about a specific Pfadmin command, type

pfadmin ? 

The Setacl Command
Pfadmin's most useful command is probably Setacl, which lets you set the ACL on a specific public folder or on all public folders. The command's syntax is

pfadmin []  setacl |all  []

For example, the command

pfadmin sam setacl "bag end" gimli E

uses the Messaging API (MAPI) profile sam to grant the Exchange mailbox gimli Editor rights for the public folder bag end. (Figure 1 shows the execution of this command; Figure 2 shows the folder's properties afterward.)

Profile. The profile variable defines the MAPI profile under which you execute Pfadmin. The profile must be attached to a mailbox with Site Admin privileges.

Folder. The folder variable defines the public folder for which you're setting the ACL. When you reference a public folder that contains a space in its name, you need to surround the name with quotation marks. Instead of an individual folder, you can specify all to set the ACLs of all public folders.

User. The user variable is the display name of the mailbox belonging to the user account to which you're granting rights. To find the display name, open Microsoft Exchange Administrator, right-click the mailbox, then select Properties. You can find the display name on the General tab.

You can define the user variable as Default to set the default rights that Exchange will automatically assign to any new user you add to the public folder's ACL. For example, suppose you want to set up a public folder and you want users with access to that folder to be able to read content only. Rather than change permissions on an individual basis as you add users to the ACL, you can simply use Pfadmin's Setacl to set the Default role's rights to Read. Then, everyone you add to the ACL will automatically have that right.

Rights. The rights variable defines the rights you want to grant to the specified user account. You can choose from two kinds of rights: rights by role and specific rights. Rights by role grant the specified user account privileges according to the following roles:

Specific rights grant rights on an individual basis. You can choose from the following rights:

You can assign the Using All (L) right to grant the specified user account both the Owner and Contact rights. Or you can use the Remove (X) right to delete the existing entry for the specified user.

The rights variable is case sensitive, so be sure to use the proper capitalization. You can specify user rights by either the representative character or characters or by the right's full name.

You can mix and match rights. For example, if you need to give a user more rights than the Author role allows but you don't want to make the user an Editor, determine the differences between the Author and Editor roles. Then grant the user the Author role and make specific rights additions to add rights (or don't assign a role and use only specific rights to grant rights one by one). To combine rights, you can use the pipe symbol (|) with optional blanks (e.g., read | write) or you can simply join the rights' representative characters (e.g., rw).

Not So Fast
As you can see, Pfadmin's Setacl command can be extremely helpful—but it contains a major glitch. When I used the previous example on my Exchange 5.5 Service Pack 4 (SP4) and SP3 servers, I consistently received the following error message:

PFADMIN v1.3.0>PFADMIN sam setacl "bag end" gimli ECMapiSession::GetAddressBook: m_pMapiSession->OpenAddressBook failed, error = 0x40380

I researched the problem but couldn't find an answer. Finally, I contacted Microsoft—and discovered that the error was discussed in the previously unpublished article "XADM: The Pfad min Utility Does Not Work with Error Message: OpenAddressBook Failed, Error 0x40380," which is now avail-able at http://support.microsoft.com/support/kb/articles/q246/6/02.asp. To summarize, the article explains that profiles you create in Outlook 2000 (or upgrade from Outlook 98 to Outlook 2000) might not work.

Apparently, this bug exists regardless of the Outlook version (if any) on your workstation or server. I don't know what changed about profiles from Outlook 98 to Outlook 2000 or why that change affects only the Setacl command, but the cure that the article describes worked. After rummaging around, I found an old Outlook 97 CD-ROM, created an Outlook 97 profile, and used it successfully with Pfadmin's Setacl. To avoid running up against this problem when you use Pfadmin, use Outlook 97 to set up a profile called pfadmin user—and guard that profile with your life.

Stay Tuned
Like Setacl, Pfadmin's other commands offer a wealth of functionality. In my next column, I'll describe these commands and how you can use them to boost your administrative power.