7.2. Configuration Options

The logic necessary to implement many of the settings described in Appendix A are present in the MSI.  Most of these can be controlled by setting the corresponding properties to the desired value.  Some settings may require modifying existing registry entries (though not recommended) or adding new resources (like files or registry keys).  Instructions for performing these tasks are below.

7.2.1 Configurable Properties

Most configurable properties correspond to registry keys or values.  Due to the logic invoked based on the existence of these registry keys or values, they are only set if the associated property is defined to have a non null value.  If the associated property is not defined in the MSI, the registry key or value will not be touched.  By default, the MSI does not contain these properties and hence will not set the registry keys.  You will need to add properties as needed to the MSI.

When one of the configurable properties is set, the installer will use the property value to set the corresponding setting in the HKEY_LOCAL_MACHINE registry hive.  The HKEY_CURRENT_USER hive is not touched by the installer.

For each property, the associated registry setting is referenced by the same text used in Appendix A.

Strings are quoted using single quotes (e.g. 'a string'). An empty string is denoted as ''.  Note that you can't author null values into the 'Property' table.

Numeric values should be authored as decimal strings.

7.2.1.1 Setting Properties

In order to set a property,

  1. Open the MSI in ORCA.EXE

  2. Select the 'Property' table from the list of tables on the left.

  3. Find the property in the list of properties on the right, double click the value and type the new value.

  4. If the property does not exist in the property list, right click the list and select 'Add Row', type the property name and the desired value.

7.2.1.2 OpenAFS for Windows Properties

(Service parameters):

[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\Parameters]

(Network provider):

[HKLM\SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider]

(OpenAFS Client):

[HKLM\SOFTWARE\OpenAFS\Client]

7.2.1.2.1 Registry Properties

These properties are used to set the values of registry entries associated with OpenAFS for Windows.

AFSCACHEPATH

Registry key    : (Service Parameters)

Registry value : CachePath

Valid values    : string .

AFSCACHESIZE

Registry key    : (Service Parameters)

Registry value : CacheSize

Valid values    : numeric

AFSCELLNAME

Registry key    : (Service Parameters)

Registry value : Cell

Valid values    : string

FREELANCEMODE

Registry key    : (Service Parameters)

Registry value : FreelanceClient

Valid values    : '1' or '0'

HIDEDOTFILES

Registry key    : (Service Parameters)

Registry value : HideDotFiles

Valid values    : '1' or '0'

LOGONOPTIONS

Registry key    : (Network Provider)

Registry value : LogonOptions

Valid values    : '0', '1' or '3'

See Appendix A section 2.1 (Domain Specific Configuration keys for Network Provider) for more details.

MOUNTROOT

Registry key    : (Service Parameters)

Registry value : Mountroot

Valid values    : string

NETBIOSNAME

Registry key    : (Service Parameters)

Registry value : NetbiosName

Valid values    : string (at most 15 characters)

NOFINDLANABYNAME

Registry key    : (Service Parameters)

Registry value : NoFindLanaByName

Valid values    : '1' or '0'

RXMAXMTU

Registry key    : (Service Parameters)

Registry value : RxMaxMTU

Valid values    : numeric

SECURITYLEVEL

Registry key    : (Service Parameters)

Registry value : SecurityLevel

Valid values    : '1' or '0'

SMBAUTHTYPE

Registry key    : (Service Parameters)

Registry value : SMBAuthType

Valid values    : '0','1' or '2'

STOREANSIFILENAMES

Registry key    : (OpenAFS Client)

Registry value : StoreAnsiFilenames

Valid values    : '0' or '1'

This option is no longer supported as of 1.5.50 now that all file names are stored to AFS file servers using the UTF-8 encoding of Unicode.

USEDNS

Registry key    : (Service Parameters)

Registry value : UseDNS

Valid values    : '1' or '0'

7.2.1.2.2 AFSCreds.exe Properties

These properties are combined to add a command line option to the shortcut that will be created in the Start:Programs:OpenAFS and Start:Programs:Startup folders (see CREDSSTARTUP).  The method of specifying the option was chosen for easy integration with the Windows Installer user interface.  Although other methods can be used to specify options to AFSCREDS.EXE, it is advised that they be avoided as transforms including such options may not apply to future releases of OpenAFS.

CREDSSTARTUP

Valid values    : '1' or '0'

Controls whether AFSCreds.exe starts up automatically when the user logs on.  When CREDSSTARTUP is '1' a shortcut is added to the 'Startup' folder in the 'Program menu' which starts AFSCREDS.EXE with the options that are determined by the other CREDS* properties.

CREDSAUTOINIT

Valid values    : '-a' or ''

Enables automatic initialization.

CREDSIPCHDET

Valid values    : '-n' or ''

Enables IP address change detection.

CREDSQUIET

Valid values    : '-q' or ''

Enables quiet mode.

CREDSRENEWDRMAP

Valid values    : '-m' or '’

Enables renewing drive map at startup.

CREDSSHOW

Valid values    : '-s' or ''

Enables displaying the credential manager window when AFSCREDS starts up.

7.2.2 Existing Registry Entries

You can change existing registry values subject to the restrictions mentioned in the Windows Platform SDK.  Pay special attention to component key paths and try to only change the 'Value' column in the 'Registry' table.  If you want to add additional registry keys please refer to section 3 (Additional resources).

7.2.3 Replacing Configuration Files

The OpenAFS configuration files (CellServDB) can be replaced by your own configuration files.  These files are contained in separate MSI components so that you can disable them individually.

The recommended method for replacing these files is to first disable the components containing the configuration files that you want to replace, and then add new components for the replacement files.  This is outlined below (assuming you are using ORCA.EXE to author the transform).

Note that transforms are not a good way to add a new file as an embedded stream.  The method outlined here places the file in the same directory as the MSI for deployment.

The walkthrough below is to add a custom 'CellServDB' file.

  1. Disable the component that contains the configuration file that you want to replace.

    1. Locate and select the 'Component' table in the 'Tables' list.

    2. In the Component table, locate the component you need to change ( Ctrl-F invokes the 'Find' dialog).  The component names are listed below in section 7.2.3.1.  For this example, the component name is 'elf_CellServDB'.

    3. Go to the 'Condition' column of the component.

    4. Enter a condition that evaluates to false. I.e. 'DONOTINSTALL'. (Note that an undefined property always evaluates to false).

      Note that you can also use this step to disable other configuration files without providing replacements.

  2. Add a new component containing the new configuration file.

    1. Select the 'Component' table in the 'Tables' list.

    2. Select 'Tables'->'Add Row' (Ctrl-R).

    3. Enter the following :

      Component

      cmf_my_CellServDB

      ComponentID

      {7019836F-BB2C-4AF6-9463-0D6EC9035CF1}

      Directory_

      dirClient

      Attributes

      144

      Condition

       

      KeyPath

      fil_my_CellServDB

      Note that the ComponentId is an uppercase GUID.  You can generate one using GUIDGEN.EXE or UUIDGEN.EXE, both of which are included in the Platform SDK.

      The Attributes value of 144 is a sum of msidbComponentAttributesPermanent (16) and msidbComponentAttributesNeverOverwrite (128).  This ensures that local modifications are not overwritten or lost during an installation or uninstallation.  These are the same settings used on the default configuration files.

                  'fil_my_CellServDB' is a key into the 'File' table which we will fill later.

  3. Add a new feature to hold the new component.

    1. Select the 'Feature' table.

    2. Add a new row (Ctrl-R or 'Tables'->'Add Row') with the following values:

      Feature

      fea_my_CellServDB

      Feature_Parent

      feaClient

      Title

       

      Description

       

      Display

      0

      Level

      30

      Directory_

       

      Attributes

      8

      It is important to create the new feature under the 'feaClient' feature, which will ensure that the configuration file will be installed when the client binaries are installed.

      Setting 'Display' to 0 will hide this feature from the feature selection dialog during an interactive installation.  A value of 30 for 'Level' allows this feature to be installed by default (on a 'Typical' installation).

      The 'Attributes' value is msidbFeatureAttributesDisallowAdvertise (8), which is set on all features in the OpenAFS MSI.  The OpenAFS MSI is not designed for an advertised installation.

  4. Join the component and the feature.

    1. Select the 'FeatureComponents' table.

    2. Add a new row with the following values:

      Feature

      fea_my_CellServDB

      Component

      cmf_my_CellServDB

  5. Add an entry to the 'File' table.

    1. Select the 'File' table.

    2. Add a new row with the following values:

      File

      fil_my_CellServDB

      Component_

      cmf_my_CellServDB

      FileName

      CellServDB

      FileSize

      (enter file size here)

      Attributes

      8192

      Sequence

      1000

                      (leave other fields blank)

      The 'Attributes' value is msidbFileAttributesNonCompressed (8192).  This is because we will be placing this file in the same directory as the MSI instead of embedding the file in it.  Transforms do not support updating compressed sources or adding new cabinet streams.

      Finally, the 'Sequence' value of 1000 will be used later to distinguish the file as being in a separate source location than the other files in the MSI.

  6. Set a media source for the file.

    1. Select the 'Media' table.

    2. Add a row with the following values :

      DiskId

      2

      LastSequence

      1000

                      (leave other fields blank)

      The sequence number of 1000 designates this as the media source for the newly added file.

7.2.3.1 Components for Configuration Files

CellServDB: 'cpf_CellServDB' (ID {D5BA4C15-DBEC-4292-91FC-B54C30F24F2A})

7.2.4 Adding Domain Specific Registry Keys

Following is an example for adding domain specific registry keys.

    Refer to Appendix A section 2.1 for more information.

    Columns that are unspecified should be left empty.

    We create a new feature and component to hold the new registry keys.

    'Feature' table:

            (new row)             Feature            : 'feaDomainKeys'             Feature Parent : 'feaClient'             Display           : 0             Level               : 30             Attributes        : 10

    'Component' table:

            (new row)             Component     : 'rcm_DomainKeys'             ComponentId  : '{4E3FCBF4-8BE7-40B2-A108-C47CF743C627}'             Directory         : 'TARGETDIR'             Attributes        : 4             KeyPath          : 'reg_domkey0'

    'FeatureComponents' table:

            (new row)             Feature            : 'feaDomainKeys'             Component     : 'rcm_DomainKeys'

    'Registry' table:

            (new row)             Registry          : 'reg_domkey0'             Root                : 2             Key                 : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain'             Component     : 'rcm_DomainKeys'

            (new row)             Registry          : 'reg_domkey1'             Root                : 2             Key                 : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain'             Name              : '*'             Component     : 'rcm_DomainKeys'

            (new row)             Registry          : 'reg_domkey2'             Root                : 2             Key                 : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\ATHENA.MIT.EDU'             Name              : '*'             Component     : 'rcm_DomainKeys'

            (new row)             Registry          : 'reg_domkey3'             Root                : 2             Key                 : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\ATHENA.MIT.EDU'             Name              : 'LogonOptions'             Value              : 1             Component     : 'rcm_DomainKeys'

            (new row)             Registry          : 'reg_domkey4'             Root                : 2             Key                 : SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'             Name              : '*'             Component     : 'rcm_DomainKeys'

            (new row)             Registry          : 'reg_domkey5'             Root                : 2             Key                 : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'             Name              : 'LogonOptions'             Value              : 0             Component     : 'rcm_DomainKeys'

            (new row)             Registry          : 'reg_domkey6'             Root                : 2             Key                 : 'SYSTEM\CurrentControlSet\Services\TransarcAFSDaemon\NetworkProvider\Domain\LOCALHOST'             Name              : 'FailLoginsSilently'             Value              : 1             Component     : 'rcm_DomainKeys'

 

The example adds domain specific keys for 'ATHENA.MIT.EDU' (enable integrated logon) and 'LOCALHOST' (disable integrated logon and fail logins silently).

7.2.5 Adding Site Specific Freelance Registry Keys

Following is an example for adding site specific Freelance registry keys to pre-populate the Mountpoints and Symlinks in the fake root.afs volume.

    Columns that are unspecified should be left empty.

    We create a new feature and component to hold the new registry keys.

    'Feature' table:

            (new row)             Feature            : 'feaFreelanceKeys'             Feature Parent : 'feaClient'             Display           : 0             Level               : 30             Attributes        : 10

    'Component' table:

            (new row)             Component     : 'rcm_FreelanceKeys'             ComponentId  : '{4E3B3CBF4-9AE7-40C3-7B09-C48CF842C583}'             Directory         : 'TARGETDIR'             Attributes        : 4             KeyPath          : 'reg_freekey0'

    'FeatureComponents' table:

            (new row)             Feature            : 'feaFreelanceKeys'             Component     : 'rcm_FreelanceKeys'

    'Registry' table:

            (new row)             Registry          : 'reg_freekey0'             Root                : 2             Key                 : 'SOFTWARE\OpenAFS\Client\Freelance'             Component     : 'rcm_FreelanceKeys'

            (new row)             Registry          : 'reg_freekey1'             Root                : 2             Key                 : 'SOFTWARE\OpenAFS\Client\Freelance'             Name              : '0'             Value              : 'athena.mit.edu#athena.mit.edu:root.cell.'             Component     : 'rcm_FreelanceKeys'

            (new row)             Registry          : 'reg_freekey2'             Root                : 2             Key                 : 'SOFTWARE\OpenAFS\Client\Freelance'             Name              : '1'             Value              : '.athena.mit.edu%athena.mit.edu:root.cell.'             Component     : 'rcm_FreelanceKeys'

            (new row)             Registry          : 'reg_freekey3'             Root                : 2             Key                 : 'SOFTWARE\OpenAFS\Client\Freelance\Symlinks'             Component     : 'rcm_FreelanceKeys'

            (new row)             Registry          : 'reg_freekey4'             Root                : 2             Key                 : 'SOFTWARE\OpenAFS\Client\Freelance\Symlinks'             Name              : '0'             Value              : 'athena:athena.mit.edu.'             Component     : 'rcm_FreelanceKeys'

            (new row)             Registry          : 'reg_freekey5'             Root                : 2             Key                 : 'SOFTWARE\OpenAFS\Client\Freelance\Symlinks'             Name              : '1'             Value              : '.athena:.athena.mit.edu.'             Component     : 'rcm_FreelanceKeys'

The example adds a read-only mountpoint to the athena.mit.edu cell's root.afs volume as well as a read-write mountpoint.  Aliases are also provided using symlinks.