
			Solaris(R) PC NetLink 1.2
			   Performance Issues
			      January, 2002

------------------------------------------------------------------------

This document discusses the following topics:

- Tuning for Better File Copy Performance
- Optimizing ACL Database Size and Speed

------------------------------------------------------------------------

Tuning for Better File Copy Performance
---------------------------------------

PC NetLink contains two registry parameter settings, MaxMessageSize
and NameSpaceMapping, that you can change to improve performance on
file copy operations. These parameters are independent of the changes
in this patch.

1. The MaxMessageSize parameter is under the registry key:

    SYSTEM/CurrentControlSet/Services/AdvancedServer/Parameters

The default value for MaxMessageSize is 4160. To set this value to
65535 (ffff hex), become superuser and type the following command on
one line at the system prompt:

    regconfig SYSTEM/CurrentControlSet/Services/AdvancedServer/Parameters \
	MaxMessageSize REG_DWORD 65535

2. The NameSpaceMapping parameter is under the registry key:

    SYSTEM/CurrentControlSet/Services/AdvancedServer/FileServiceParameters

This parameter allows you to turn on and off the support for DOS-style
8.3 filenames (also referred to as shortnames). Some applications
convert longer filenames to 8.3 in a format similar to the following:

	prefix~1.typ

Setting the NameSpaceMapping parameter to turn off shortname support improves directory search times, especially in directories containing large numbers of files.


The default value of NameSpaceMapping is 3; this value indicates support for both shortnames and long filenames. This setting can result in long search times because the shortnames must be created and returned for every non-8.3 name, every time a directory listing is requested, or every time a wildcard search is done (including every file copy operation). If you copy the contents of a directory, shortnames must be created and returned for every file in that directory.

NOTE: You should only turn off shortname support if you are sure that none of your installed applications uses 8.3 filenames.

The NameSpaceMapping parameter is under the registry key:

    SYSTEM/CurrentControlSet/Services/AdvancedServer/FileServiceParameters

To set the value of NameSpaceMapping to 2 (turn off shortname support
and just support long filenames), type the following command on one
line at the system prompt:

    regconfig SYSTEM/CurrentControlSet/Services/AdvancedServer/\
	FileServiceParameters NameSpaceMapping REG_DWORD 2

-------------------------------------------------------------------------

Optimizing ACL Database Size and Speed
--------------------------------------

Patch 110179-04 contains some new options that allow you to adjust ACL
behavior in PC NetLink. These options can help to reduce the growth of
the ACL database by controlling the creation of new file ACLs, or to
delete extraneous ACLs. These options thus help improve the speed of
all file access operations.

The new options included in this patch are as follows:

- the ForceFileAcl registry parameter
- the -X and -XX flags for acladm

In addition to the new ACL options, patch 110179-04 also includes
performance improvements in the ACL blob database itself. For more
information on this feature, refer to the description for bugid
4379181 in the README file.

ACL Behavior
------------

The new options implemented for this RFE can be used to improve
performance at the expense of strict conformance to Windows NT ACL
semantics. Use of these options implies acceptance of non-standard
behavior in regard to ACLs.

To understand whether use of these options is appropriate, it is
necessary have some understanding of the implications for ACL
behavior.

In NT there is an ACL on every file and directory, as well as some
other kinds of objects in the system.  These ACLs are maintained as
part of the file system.

PCNL currently stores ACLs in a database.  One consequence of this is
that when the size of the database becomes large, performance can
deteriorate.  This is a function of the number of files in PCNL
shares, the number of users, and typical activity on the system.

As an optimization, the system provides the concept of "virtual ACLs."
These ACLs inherit their characteristics from the parent directory,
combined with information about the owner of the file (if the NT user
account is mapped to a UNIX user account).  If no specific changes
are made to the ACL on an individual file, this "virtual ACL" will be
the same as an "explicit" ACL stored in the database. The system
makes the substitution dynamically, and it is transparent to the user.
If the user modifies the ACL on a file, then an explicit ACL is
created so that the change can be accurately represented. This ACL
creation behavior, combined with the ingrained habit of many users
(and administrators) to use the check box that propagates the change
to subdirectories, tends to result in growth of the database over
time. For some customer sites, this has been a significant issue.

In the PCNL software, there has always been a choice between strict
NT conformance (an explicit ACL for every file) and a conservative
approach to the optimization described above, resulting in behavior
that closely approximates NT behavior. This is controlled by the
registry parameter ForceFileAcl.

ForceFileAcl Values
--------------------

The default value for ForceFileAcl is 0, which means the system will
not create an explicit ACL for a file when it will be the same as
the virtual ACL.  A "virtual ACL" will be inherited from the parent
directory.  This provides a performance improvement over always
creating an ACL, with a close approximation of NT ACL semantics.

When the value for ForceFileAcl is set to 1, an explicit ACL will
always be created for every file. This provides exact conformance to
NT semantics, at some cost in performance.

The following new values for ForceFileAcl are implemented in this patch:

ForceFileAcl 2: No ACL will be created unless the owner is different from
 		the owner of the parent directory.

ForceFileAcl 3: No ACL will be created for an ordinary file for any reason.

These options provide ACLs at the directory level, but not at the
level of an individual file. File ACLs will be created dynamically,
based on the ACL on the parent directory and the UNIX owner (if
the NT account is mapped to a UNIX account).

In both cases (that is, when ForceFileAcl is set to either 2 or 3), if the owner of the file is different from the owner of the
parent, and the owner is mapped to a UNIX account, the UNIX ownership will
be maintained so that the owner will be represented correctly. Customers
who do not have mapped UNIX accounts should use option 2 if file ownership
is significant for administrative or policy reasons.

These options are intended for customers who have a problem with ACL
performance. Fewer ACLs will be created, keeping the size of the
database down. In addition, using one of these options results in
fewer write access operations to the database, substantially reducing
contention for write locks on the database among tasks supporting
different clients. While the resulting change in performance has not
yet been measured, and is very dependent on the characteristics of
a particular site, performance improvement appears to be significant.

In both cases (ForceFileAcl values 2 and 3), this change only prevents
the creation of new ACLs.  It will not remove any ACLs that are
already present.  If you want to delete an existing ACL, use the new
-X or -XX options with the acladm command. (For more information on
acladm, refer to the description below.)

NOTE: It is strongly recommended that you run the acladm command to
delete existing ACLs when you set ForceFileAcl to either 2 or 3.
In this case, running acladm should significantly reduce the size of
the ACL database. Once the number of existing ACLs has been reduced,
using the new ForceFileAcl option should halt or slow the growth of
the ACL database.

NOTE: It is important to understand that attempts to modify an ACL
where we will not create one will get a success status, but since
there is no ACL, the change will not really be made. If the NT account
is mapped to a UNIX account, the UNIX ownership will be changed
accordingly, but no real ACL is maintained.

For true NT compatibility, do not use these options. This behavior is
intended only for sites that choose to implement non-standard ACL
behavior in order to obtain the resulting shrinkage of the ACL
database and improved performance.


How to Change ForceFileAcl
--------------------------

ForceFileAcl is a registry parameter. This means that you can either
use the regconfig command supplied with PCNL to change its value, or
you can use the NT registry editing program regedt32.

NOTE: Make sure you are loged in as superuser to use regconfig.

ForceFileAcl exists under the registry key:

    SYSTEM/CurrentControlSet/Services/AdvancedServer/FileServiceParameters

Please note that any value other than 0, 1, 2 or 3 is not valid.
(Invalid values of this parameter are treated as 1.)


Using the acladm Option to Delete File ACLs
--------------------------------------------

The acladm utility has two new options that will delete ACLs on all
ordinary files. The option has 2 variations:

    acladm -X	deletes all ACLs on ordinary files except where the
		owner is different from the owner of the parent.

    acladm -XX	deletes ALL ACLs on ordinary files.

In both cases, ACLs on directories and non-file objects (such as
shares or printer queues) are preserved.

For better understanding of the use of this option and its
corresponding effect on performance, refer to the section
entitled ACL Behavior.

