< Previous PageNext Page >

Hide TOC

Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Authorization, File Ownership, and Permissions

This section describes how permissions are set for files and directories during installation with PackageMaker and Installer. It also describes how to specify authorization requirements, and when the user will be required to authenticate.

File Ownership

By default, if no authorization is required, the files that Installer places on a user’s computer are owned by the user doing the installation. If authorization is required, the files are owned by the owner specified in the files archive within the package, regardless of the user and password supplied to complete the authentication. So if your software requires authorization, make sure all of the files and directories have the desired owner and group when you set up a directory structure prior to creating a package. See “Setting File Ownership and Permissions” for suggestions on how to do this.

Authorization and authentication are described in “Authorization for an Installation.”

File Permissions

By default, the files and directories that Installer places on a user’s computer have the permissions specified in the package’s archive. You can override the default permission settings for installed directories (but not files) by selecting the Overwrite Permissions option in the PackageMaker Info pane. This instructs Installer to use the permissions of directories in the package to modify the permissions of any identically named directories found on the installation volume.

Warning: Use this option with care. If the installation sets the permissions of files in the root directory incorrectly, the installation of the package could render the target computer unusable. For related information, see “Things to Look Out For.”

To elaborate on how permissions are set for installed files and directories:

All installed files get their permissions from the package’s file archive.
All installed directories that don’t already exist on the target volume get their permissions from the package’s file archive.
All directories that already exist on the target volume keep their current permissions, unless the package specifies the Overwrite Permissions option.
In some cases, setting the desired permissions may require authorization. You can request authorization as described in “Authorization for an Installation.”

In general, when you set up a directory structure for your software prior to creating a package, make sure all of the permissions are set as you want them when installed. See “Setting File Ownership and Permissions” for suggestions on how to do this.

Setting File Ownership and Permissions

For the majority of installations, which install a relocatable application, you can do the following:

Set the Default Location (in the PackageMaker Info pane) to /Applications.
Note: It’s a good idea to always specify as much directory structure as you can in the default location and as little as possible in your package.
Set permissions for the directories and executable files in the package to a value of 775 (full access for owner and group, read and execute access for others).
Set permissions for non-executable files to 664 (read and write access for owner and group and read-only access for others).
Note: These are suggestions. In some cases (such as for a daemon or specialized software) you may know that files in a package require other permissions. Whatever permissions you set, be sure to perform test installations with the package before distributing it.
Set an appropriate owner and group for the packaged files and directories. You can read more about how to get this information in “Obtaining Owner and Group Information.”
For example, applications often are owned by root and have a group of admin.
Note: For an application whose owner is displayed as root in a Terminal window (as in Listing 1), the owner is shown as “System” instead when you choose File > Get Info in the Finder.
System software, such as a kernel extension (or KEXT), is owned by root and has a group of wheel.
Important: This step is particularly important if your package requires authorization. If so, do not use your own owner and group settings, unless you truly want the installed files on the users system to have those settings. For more information, see “File Ownership Issues Can Cause Problems.”
Set the Authorization Action pop-up to Admin Authorization (also in the PackageMaker Info pane). See Table 1 for information about possible settings.

If your installation is not relocatable, you can do the following:

Set the Default Location to the full path in which to place the software.
Set the required permissions for the installation location.
Set an appropriate owner and group for the packaged files and directories, as described in the previous steps.
Set the Authorization Action pop-up to Admin Authorization or Root Authorization, as appropriate.

Obtaining Owner and Group Information

“Authorization, File Ownership, and Permissions” explains why, if your software requires authorization, you should make sure all of the files and directories have the desired owner and group when you set up a directory structure prior to creating a package. And “File Ownership Issues Can Cause Problems” describes what can go wrong if you don’t follow that advice. So how do you determine which owner and group to use?

If your software will be installed in a known destination, such as /Applications, you can examine the owner and group for files and directories already installed in that location. An easy way to do this is to open a Terminal window and display the information using a command such as the ls command. For example, you could type cd /Applications; ls -l (and press Return) to change location to the Applications directory and list all the files it contains, along with their permissions, owner, group, and other information.

When you do this, you should see that many files have an owner of root and a group of admin. These are values you can use for an application you place in that location. Some files and directories may be owned by the current user (which is probably you), but you don’t want to be the owner when these files are installed from your package (unless you’re packaging software just to install on your own computer).

Similarly, if you list the files in /System/Library/Frameworks, you’ll see frameworks with owner root and group wheel.

Sometimes owner, group, and permission information can be damaged or inadvertently changed, so when you check, you may see odd values. To make sure you are seeing the correct values, you can take one of several steps before you check owner and group information:

Do a clean install of Mac OS X.
Use the Repair Disk Permissions command in the Disk Utility application (located in /Applications/Utilties).

There is also another way to check the owner and group information for a destination, if the directory is part of a system installation—you can examine information from the receipt that was created when Mac OS X was installed. For example, you could use the lsbom command (located in /usr/bin) to check the .bom file in the receipt file Library/Receipts/BaseSystem.pkg. You might use the following format for the command:

lsbom -p MUGsf /Library/Receipts/BaseSystem.pkg/Contents/Archive.bom

Listing 1 shows the first few lines of output from running this command. For information on the lsbom flags used in this example, type man lsbom in a Terminal widow.

Listing 1 Output from lsbom command

drwxrwxr-t  root admin      .

drwxrwxr-x  root admin      ./Developer

drwxrwxr-x  root admin      ./Developer/Applications

drwxrwxr-x  root admin      ./Developer/Applications/Xcode.app

drwxrwxr-x  root admin      ./Developer/Applications/Xcode.app/Contents

-rw-rw-r--  root admin 13199./Developer/Applications/Xcode.app/Contents/Info.plist

drwxrwxr-x  root admin      ./Developer/Applications/Xcode.app/Contents/MacOS

-rwxrwxr-x  root admin 103072./Developer/Applications/Xcode.app/Contents/MacOS/Xcode

-rw-rw-r--  root admin   8  ./Developer/Applications/Xcode.app/Contents/PkgInfo

drwxrwxr-x  root admin      ./Developer/Applications/Xcode.app/Contents/Plug

You can also use the grep command to search through all the receipt files in /Library/Receipts for packages that have installed into a particular directory. For example, if you wanted to know which receipts recorded an installation into the /usr/share directory, you could type the following in Terminal:

grep -rs /usr/share /Library/Receipts

Listing 2 shows the first few lines of output from running this command.

Listing 2 Output from grep command

Binary file /Library/Receipts/AdditionalSpeechVoices.pkg/Contents/Archive.bom matches

Binary file /Library/Receipts/AirPortSW.pkg/Contents/Archive.bom matches

Binary file /Library/Receipts/Apr2004XcodeToolsExtras.pkg/Contents/Archive.bom matches

Binary file /Library/Receipts/AsianLanguagesSupport.pkg/Contents/Archive.bom matches

Binary file /Library/Receipts/BaseSystem.pkg/Contents/Archive.bom matches

Binary file /Library/Receipts/BluetoothUpdate1.5.pkg/Contents/Archive.bom matches

Binary file /Library/Receipts/BluetoothUpdate141.pkg/Contents/Archive.bom matches

Authorization for an Installation

Installing a package or metapackage may result in actions that require root or administrator privileges, such as copying files into a root-owned directory or copying files that have root permission.

If the user performing the installation has the required privileges, no authorization is necessary.
If the user does not have the required privileges and the package is not set up to request authorization, the installation fails and displays a dialog that it cannot proceed.
If the user does not have the required privileges and the package is set up to request authorization, Installer displays an authentication dialog as the first step of the installation.

Note: Authorization is the act of granting a right or privilege, and authentication is the act of verifying the identity of the user. Authorization uses authentication as part of its process.

Recall that if no authorization is required, the files that Installer places on a user’s computer are owned by the user doing the installation. If authorization is required, the files are owned by the owner specified in the files archive within the package, regardless of the user and password supplied to complete the authentication.

You specify an authorization level for a package using the Authorization Action pop-up menu in the PackageMaker Info pane. The available choices are Root Authorization, Admin Authorization, and No Authorization Required. The user is prompted for authorization (through an authentication dialog) only when the requested authorization is higher than the user’s current authorization at installation time. Table 1 shows the possible permissions, settings, and outcomes.

Important: Even if a package specifies root authorization, a user can authenticate by supplying the administrator password and can then install the software.

**Table 1** Possible permissions, authorization action settings, and results
User logged in as	Authorization action specified by package	Privileges Used	Result
Root	(any)	Root	Authorization not required
Administrator	Root Authorization	Root	Prompt for authorization
Administrator	Admin Authorization	Administrator	Authorization not required
Administrator	No Authorization Required	Administrator	Authorization not required
Regular user	Root Authorization	Root	Prompt for authorization
Regular user	Admin Authorization	Administrator	Prompt for authorization
Regular user	No Authorization Required	Logged-in user	Authorization not required

A metapackage requires authorization if any of its enclosed packages requires it; otherwise, a metapackage does not require authorization. A metapackage requires the highest authorization required by any enclosed package; it also requires the highest restart action of any enclosed package.

Choosing an Authorization Setting

In general, choose an authorization setting that is the same or higher than the permissions of the files in the package and the specified destination for installing them. Authorization should be set to root if any component needs to be set to root.

In specific situations, your package should request root or administrator privileges:

The package contains files that will be installed in a system-level location, such as /System, /usr, /bin, and so on; for example, KEXTs (kernel extensions) reside in /System/Library/Extensions.
The package contains files that will be installed with root or administrator permissions; see “Setting File Ownership and Permissions” for related information.

If your package is relocatable, a user can attempt to install the software in any location (unless you’ve also specified Root Volume Only). Therefore, set an Authorization level that makes sense for your software. (Relocatable and Root Volume Only are options you set in the PackageMaker Info pane.)

Note: It is not recommended that you use the scripts described in “Modifying an Installation With Scripts” to modify file permissions.

Things to Look Out For

The following are some installation issues to be aware of.

Installing Can Change Permissions of a User’s Directories

Suppose you want to create a package to install a utility in /Applications/Utilities, a directory that typically exists on all boot volumes. Further, suppose that in creating the package, the utility application resides in the directory Package_contents/Applications/Utilities, which has permissions settings of 750 (full access for owner, read and execute access for group, and no access for others), and you specify a default installation location of /.

If you select the Overwrite Permissions checkbox in the PackageMaker Info pane, Installer uses the permissions of directories in the package to modify the permissions of any identically named directories found on the installation volume. This may result in an error if your package does not require authorization (see “Restrictive Permissions Can Cause an Installation to Fail.”

Even if your packages does require authorization, you may still have a problem. After installation, the user’s /Applications/Utilities directory has permissions of 750. If the directory previously had a more (or less) permissive setting, the user may be confused and unhappy when the directory can no longer be accessed in the same way as before.

Note: The Overwrite Permissions checkbox might more accurately be titled Overwrite Existing Directory Permissions, because it affects only directories, not files.

This suggests you should select the Overwrite Permissions checkbox only if you are certain that you know better than the user what the directory permissions should be. One such example might be if you are doing net installations in an educational environment.

Installing Can Convert Symbolic Links to Actual Directories

Again, suppose your package installs a utility application in /Applications/Utilities, a directory that typically exists on all boot volumes. In this scenario, suppose the user has replaced Utilities with a symbolic link (alias) to a Utilities directory on a different drive.

By default, Installer replaces links with directories, which again is likely to confuse (and annoy) the user, since it will “orphan” whatever the symbolic link points to. In this case, the user would end up with a Utilities directory containing just your utility, while their original Utilities directory has been set adrift.

PackageMaker currently has no user interface option to control how Installer handles symbolic links. However, there is a way you can change the default behavior so that Installer follows symbolic directory links, rather than replaces them. To do so, you edit the Info.plist file for the package and set the value for the IFPkgFlagFollowLinks key to Yes. For more information on making these kinds of changes, see “Examining and Modifying Property Lists.”

Restrictive Permissions Can Cause an Installation to Fail

Suppose you set the permissions to a restrictive value. If you do not set the Authorization Action pop-up (in the PackageMaker Info pane) to require root or administrator authorization for the package, the installation may fail for a user who isn’t logged in with high enough permissions.

File Ownership Issues Can Cause Problems

Suppose your package installs a framework in /System/Library/Frameworks, which has an owner of root. Suppose the Frameworks directory you use to create your package has you (jbob3) as the owner. You set the package to request root authorization so that it can be installed in the Frameworks directory.

Because the user is authorized as root, the Installer is also root and can install files using owner jbob3. This translates to some user ID number that is likely to be of little value to the current user. And in fact, the user may experience serious problems, as the system may not be able to function properly because it doesn’t own files it expects to own.

You can minimize problems of this nature by following the advice provided in “Setting File Ownership and Permissions.”