Previous Page | Next Page

Configuration Files

Reference Information for omaconfig.xml

About the omaconfig.xml File

The omaconfig.xml file specifies changes to standard features of the SAS Metadata Server, the repository manager, and policies related to internal users. The features that can be changed include the following:

For options that are omitted from the omaconfig.xml file, the server uses the option's default value.

Your omaconfig.xml file might include an option that activates a SAS Metadata Server or repository manager feature that is needed by a particular SAS application. When this is the case, do not remove the option or change its setting unless you are instructed to do so by SAS Technical Support.

The omaconfig.xml file is located in the following path: sas-configuration-directory\Lev1\SASMeta\MetadataServer.

When you change any option in omaconfig.xml, you must stop and restart the metadata server for the change to take effect. For instructions, see Operating Your Servers.

CAUTION:
Stopping the metadata server stops other components.   [cautionend]

The file can contain the following XML elements:

<OMA>

specifies options for the metadata server.

<RPOSMGR>

specifies options for the repository manager.

<InternalAuthenticationPolicy>

specifies options for the assignment and management of passwords for internal users. Internal accounts are accounts that exist only in metadata (see "Internal Accounts" in the "Authentication Mechanisms" chapter in the SAS Intelligence Platform: Security Administration Guide).

<OMA> Options

The <OMA> element specifies the following options for the metadata server:

ADMINUSERS="path-and-filename"

specifies the name and location of the adminUsers.txt file. A planned installation creates the file in sas-configuration-directory\Lev1\SASMeta\MetadataServer\adminUsers.txt.

ALERTEMAIL="email-address"

specifies an e-mail address to which the metadata server will send a notification message when an error occurs that prevents the disk update process for the journal from completing. To specify more than one address, enclose each address with single quotation marks, place a blank space between each address, and enclose the list with parentheses. For example: 

"('Bill@mycompany.com' 'Susan@mycompany.com')"

Note:   For the ALERTEMAIL, ALERTEMAILATTACHMENT, and ALERTEMAILTEST options to work, the appropriate mail server connection properties (EMAILSYS, EMAILHOST, EMAILPORT, and EMAILID) must be specified in the metadata server's sasv9.cfg or sasv9_usermods.cfg file. See Options for the Metadata Server Invocation Command.  [cautionend]

ALERTEMAILATTACHMENT="path-and-filename"

specifies the relative path and filename of an existing file to attach to the ALERTEMAIL message. The path should be relative to the directory from which the metadata server is started. For example:

  • To attach the metadata server's omaconfig.xml file, which is located in the same directory as the script that starts the server, specify just omaconfig.xml.

  • to attach the metadata server's sasv9.cfg file, which is located in the same directory as the script that starts the server, specify just sasv9.cfg.

  • to attach the sasv9.cfg file from the SASMeta directory, specify ..\sasv9.cfg.

ALERTEMAILTEST

enables you to verify that the ALERTEMAIL and ALERTEMAILATTACHMENT options are set correctly. ALERTEMAILTEST is a temporary omaconfig.xml option that causes a test message to be sent at server startup in order to verify that the e-mail address and filename specified in the ALERTEMAIL and ALERTEMAILATTACHMENT options are valid. An error will cause the e-mail not to be sent and the metadata server to be stopped, so that the administrator can investigate which option has a problem. The metadata server is also stopped when the e-mail is sent correctly so that the administrator can remove the ALERTEMAILTEST option from the omaconfig.xml file. The SAS Metadata Server will not run with the ALERTEMAILTEST option set. Be sure to specify a string value for the ALERTEMAILTEST options. Using the option without a value can also prevent the e-mail from being sent.

GROUPSFORMEMBERASSOCDELETE="comma-separated-list-of-groups"

invokes special functionality that is needed by SAS Information Delivery Portal. This option specifies the names of groups that allow a member to be deleted by a user who has WriteMetadata permission for the member, even though the user does not have WriteMetadata permission for the group itself. Only the groups listed on this option allow the behavior; other groups continue to use the default security for the membership list. The following groups need special processing:

  • DESKTOP_PORTALPAGES_GROUP

  • Portlet Template Group

  • OrderingGroup

  • DESKTOP_PAGEHISTORY_GROUP

  • Portal Collection

The names are case sensitive. The GROUPSFORMEMBERASSOCDELETE option is added to the omaconfig.xml file by the planned SAS installation. Do not change the names unless instructed to do so by SAS Technical Support. If this option is removed from the omaconfig.xml file, owners of information maps, reports, and stored processes, as well as others who have WriteMetadata permission to the metadata describing these items, will not be able to delete the items if someone has created a bookmark to them in the SAS Information Delivery Portal.

JNLPRE="1 | Y | T | 0 | N | F"

specifies whether a client identifier is to be included in the preamble of log messages for the metadata server.

If you specify 1, Y, or T, then it is not necessary to include the characters %u in the conversion pattern for the metadata server log. Doing so would cause the client identifier to appear twice in log messages.

Default: 0

Note:   The default setting is 0 because the default logging configuration for the metadata server includes a conversion pattern with the characters %u, which provides the client identifier.  [cautionend]
JOURNALPATH="path-and-filename"

specifies a location to create the journal file.

When specifying a location, keep these things in mind:

  • For consistency, we recommend that you specify the filename MetadataJournal.dat.

  • For convenience and ease of management, the standard metadata server configuration creates repositories and the metadata server log on the same file system in which the metadata server is started. If it is at all likely that this file system will fill up, consider moving the repositories to another file system. If the server file system fills up, the journal file is not threatened because it is a fixed size. However, the metadata server log will need space to be able to record any disk-full messages in order to send them to the metadata server administrator.

    To change the location of the journal file, follow the detailed instructions in Move the Journal File to Another File System.

  • Put the journal file on a native file system, such as the C: (system) drive. The location should be fast and highly reliable. Do not place the file on a network-mounted file system or network appliance.

  • If you use the same file system in which in which the metadata server is started, use a relative pathname to identify the file's location. The pathname should be relative to the directory from which the metadata server is started.

If you want to disable journaling, then specify a blank string ("") for this option.

Note:   For optimum performance and to ensure system integrity in the event of a failure, it is strongly recommended that journaling be enabled at all times.  [cautionend]

Default: If you do not specify this option, then the journal is created in SAS-configuration-directory\Lev1\SASMeta\MetadataServer\Journal\
MetadataJournal.dat.
JOURNALSIZE="number-of-bytes"

specifies a size, in bytes, for the journal file. This space is reserved in the file system and is unavailable to other processes, whether the journal file is full or not.

The size that you assign to the journal file depends on the total disk space available on the SAS Metadata Server host machine. On 32-bit machines and z/OS machine, the default size is 200MB. On 64-bit machines, 500MB is the default setting. The default settings should be sufficient for most sites.

If clients regularly experience delays in getting their add, update, and delete requests processed, check the SAS Metadata Server log. If you find messages similar to the following, you might consider setting a higher JOURNALSIZE value: 

WARNING: insufficient file space available in journal file.

When an entry is added to the journal file, it is marked as Pending. When entries are committed to the disk repository, they are marked as Done, and the space becomes available for new pending entries. If the rate at which entries are being added exceeds the rate at which they are completed, the journal file can become full, and not enough space is available for new entries. When this occurs, the metadata server waits until the update process can catch up. When the contents of the journal file are safely committed, the first new update is written directly to repositories on disk. Then, journaling resumes.

Default: 200MB on 32-bit machines and z/OS machines, and 500MB on 64-bit machines
JOURNALYIELDCOUNT="number-of-observations"

is designed to prevent large repository updates (for example, requests that add hundreds of objects) from monopolizing the server. It specifies the number of records that the update process can apply before yielding to allow other internal processing tasks, such as writing to the metadata server log, to occur and then resuming operation. For example, if JOURNALYIELDCOUNT were set to 20 and a workunit consisted of 100 records, the update process would apply 20 records, stop to allow internal processes to function, apply 20 more records, and so on, until all 100 records were applied to repositories.

This option does not affect the order in which updates are applied to repositories. Metadata updates are applied in the order in which they are received, and all repositories are locked for reading and writing at proper times. JOURNALYIELDCOUNT improves the overall performance of the metadata server by allowing those updates that have been performed on the in-memory metadata copy to be applied to the permanent copy on disk during periods of CPU availability. The in-memory copy remains up-to-date at all times.

The maximum setting of the JOURNALYIELDCOUNT option is 100 records; the minimum setting is 5 records. The default value is 14 records. Do not adjust the default value unless instructed to do so by SAS Technical Support.

MAXACTIVETHREADS="number-of-threads"

specifies the number of threads that are allowed to run concurrently on the metadata server. The number of processors determines the number of concurrent queries that can be made. If the server has only one processor, then the recommended setting is 2. If the server has more than one processor, then the recommended setting is the number of processors. A setting that is higher or lower than the recommended one can affect performance.

For information about how the metadata server uses threads, and recommendations for setting the MAXACTIVETHREADS option and the related THREADSMIN and THREADSMAX server invocation options, see Configuring the Number of Threads Used by the Metadata Server.

Default: By default, the server sets the maximum number of active threads as follows:

  • If the host machine has one processor, then the maximum active number of threads is set to 2.

  • If the host machine has two or more processors, then the maximum active number of threads is set to the number of processors.
MAXIMUM_QUERY_RETRY_COUNT="number-of-retries"

specifies the maximum number of times that a metadata query request involving multiple repositories can be restarted because of missing repository locks. If the maximum number of retries (also referred to as the "query retry limit") is reached before the query request is completed, a repository lock error is returned.

When the metadata server receives a query request, the server does the following to process the request:

  1. obtains a shared query lock for each repository that is specified in the request.

  2. as the request is prepared, verifies that a shared query lock has been obtained for each repository that contains records that are needed to complete the request.

  3. immediately attempts to obtain any shared query locks that were not obtained initially.

  4. restarts the request if the missing locks are not available. Each restart constitutes a retry.

  5. repeats the process until the request is complete or until the query retry limit is reached. If the query request cannot be completed within the query retry limit, a repository lock error is returned.

Activity that is related to obtaining repository query locks is recorded in the Metadata.CounterQueryUpdateLock counters. See Using the Server Performance Counters and Information Fields.

Default: 7 or the number of repositories that were configured when the metadata server was last started, whichever is higher
MAXIMUM_RETRY_COUNT="number-of-retries"

specifies the maximum number of times that a metadata update request involving multiple repositories can be restarted because of missing repository locks. If the maximum number of retries (also referred to as the "update retry limit") is reached before the update request is completed, a repository lock error is returned.

When the metadata server receives an update request, the server does the following to process the request:

  1. obtains an exclusive update lock for each repository that is specified in the request.

  2. prepares the request, building a transaction of all the attributes, associations, and associated objects that need to be updated, added, or deleted in any repository to successfully complete the request.

  3. before committing the transaction, verifies that exclusive update locks have been obtained for all repositories that are being updated, and restarts the request if any update locks are missing.

  4. repeats the process until the request is complete or until the update retry limit is reached. If the update request cannot be completed within the retry limit, a repository lock error is returned.

Activity that is related to obtaining repository update locks is recorded in the Metadata.CounterRetryUpdateLock counters. See Using the Server Performance Counters and Information Fields.

Default: 3
SASSEC_LOCAL_PW_SAVE="1 | Y | T | 0 | N | F"

specifies whether users of desktop applications can save their user IDs and passwords in a local metadata connection profile.

If you specify 1, Y, or T, then a Save user ID and password in this profile check box is available to users when they launch desktop applications. If a user selects this check box, then the user's ID and password are stored in the user's connection profile on the local file system. This profile is used for future connections to the metadata server. Saving the ID and password in the profile allows users to reconnect in the future without entering these values again.

If you do not want to allow IDs and passwords to be stored in client connection profiles, specify 0, N, or F.

Note:   

  • After you change the setting for this option and restart the metadata server, each client uses the previous setting for its first connection. The client then discovers the revised setting and conforms to that revised setting for subsequent connections.

  • If you change the setting to disallow saved credentials, and credentials are already present in a user's connection profile, those credentials must be manually removed.

  [cautionend]
Initial setting: 1
RETURNPASSWORDS="CLEAR|SAS001|SAS002|SAS003"

causes passwords to be encoded when they are returned from the metadata server to a requesting client. You can specify one of the following encoding methods:

CLEAR

specifies no encoding of passwords.

SAS001

specifies the use of base64 to encode passwords.

SAS002

specifies the SASProprietary encoding method. This method is included in SAS software and uses a 32-bit key to encode passwords.

SAS003

specifies the Advanced Encryption Standard (AES) encoding method. This method requires that you install SAS/SECURE. If you specify this option but you have not installed SAS/SECURE, then passwords are returned using the SAS002 (SASProprietary) encoding method.

Note:   SAS/SECURE is an add-on product that requires a separate license. For details about SAS/SECURE, the SASProprietary algorithm, and the AES algorithm, see Encryption in SAS.  [cautionend]

Initial Setting: SAS002
STOREPASSWORDS="SAS002|SAS003"

causes passwords to be encoded when they are stored in metadata. You can specify one of the following encoding methods:

SAS002

specifies the SASProprietary encoding method. This method is included in SAS software and uses a 32-bit key to encode passwords.

SAS003

specifies the Advanced Encryption Standard (AES) encoding method. This method requires that you install SAS/SECURE. If you specify this option but you have not installed SAS/SECURE, then passwords are stored using the SAS002 (SASProprietary) encoding method.

Note:   SAS/SECURE is an add-on product that requires a separate license. For details about SAS/SECURE, the SASProprietary algorithm, and the AES algorithm, see Encryption in SAS.  [cautionend]

Default: SAS003
CAUTION:
Passwords that are stored in SAS003 format become unusable and inaccessible if SAS/SECURE is unavailable.

If SAS/SECURE is installed, the default format for stored passwords is SAS003. It is important to keep your SAS/SECURE license current. If you choose to discontinue use of SAS/SECURE, you must revert all stored passwords to SAS002 format before uninstalling the software. To revert passwords, set STOREPASSWORDS="SAS002", restart the metadata server, and use SAS Management Console to re-enter passwords in any logins that need to include passwords.  [cautionend]

TRUSTEDUSERS="path-and-filename"

specifies the name and location of the trustedUsers.txt file. The planned installation creates the file in SAS-configuration-directory\Lev1\SASMeta\MetadataServer.

<RPOSMGR> Options

The <RPOSMGR> element specifies the following options for the repository manager:

LIBREF="name"

specifies an alternate libref for the repository manager. Name must be a valid SAS name. The name can be up to eight characters. The first character must be a letter (A, B, C, . . ., Z) or an underscore (_). Subsequent characters can be letters, numeric digits (0, 1, . . ., 9), or underscores. You can use uppercase or lowercase letters. SAS processes names as uppercase, regardless of how you type them. The default value is RPOSMGR.

ENGINE="libname-engine"

specifies the LIBNAME engine that is to be used to create the repository manager. The default value is an empty string; it defaults to Base SAS. When changing the default value, note that engine values must be specified in uppercase letters.

PATH="pathname"

specifies an alternate location for the repository manager. The planned installation creates the repository manager in SAS-configuration-directory\Lev1\SASMeta\MetadataServer\rposmgr. Pathname can be an absolute reference or a reference relative to the metadata server startup directory.

OPTIONS="libname-options"

specifies LIBNAME options for the repository manager. You can specify any option that is valid in a LIBNAME statement (for example, BLKSZ="").

<InternalAuthenticationPolicy> Options

The <InternalAuthenticationPolicy> element specifies the following options for the assignment and management of passwords for internal users. Internal accounts are accounts that exist only in metadata (see "Internal Accounts" in the "Authentication Mechanisms" chapter in the SAS Intelligence Platform: Security Administration Guide).

CAUTION:
The option names for <InternalAuthenticationPolicy> are case sensitive and must be entered exactly as they are shown in this list.   [cautionend]
ChangeDelayInMinutes="number-of-minutes"

specifies the number of minutes that must elapse following a password change before an internal user's password can be changed again.

Note:   This option does not apply to administrators who are setting passwords for other users.  [cautionend]

Range: 0-1440
Default: 0
DigitRequired="1 | Y | T | 0 | N | F"

specifies whether passwords for internal users must include at least one digit. To enforce this requirement, specify 1, Y, or T. To disable this requirement, specify 0, N, or F.

Default: F
ExpirationDays="number-of-days"

specifies the number of days after an internal user's password is created or changed that the password will expire and need to be changed. A value of 0 specifies that internal user's passwords will never expire.

Range: 0-32767
Default: 0
Note: You can use SAS Management Console to specify a different number of expiration days for a particular internal user's password.
ExpirePasswordOnReset="1 | Y | T | 0 | N | F"

specifies whether passwords for internal accounts are to be considered already expired when the account is created, so that users are required to change their passwords the first time they log on. To enforce this requirement, specify 1, Y, or T. To disable this requirement, specify 0, N, or F.

Interaction: This option is valid only if ExpirationDays is greater than 0.
Default: T
Exceptions:

  • This option does not apply to administrative users who reset their own passwords in SAS Management Console. When this option is in effect, administrative users who reset their own passwords in SAS Management Console are not required to change their passwords again the next time they log on.

  • You can waive the password change requirement for a specific internal user. To do so, select the never expire option in SAS Management Console when you create the user's account or when you reset the user's password. Then a password change will not be required the first time the user logs in.

    Note:   The never expire option is automatically set for the initial internal users that are created by the SAS Deployment Wizard.  [cautionend]
MinLength="number-of-bytes"

specifies the minimum allowed length for the passwords of internal users.

Range: 1-32
Default: 6
MixedCase="1 | Y | T | 0 | N | F"

specifies whether passwords for internal users must include at least one upper case letter and at least one lower case letter. To enforce this requirement, specify 1, Y, or T. To disable this requirement, specify 0, N, or F.

Default: F
NumPriorPasswords="number-of-previous-passwords"

specifies the number of previous passwords that are to be stored in each internal user's password history.

Range: 0-5
Default: 5
InactiveDaysToSuspension="number-of-days"

specifies the number of days after which an internal user's account will be suspended if the account is not used. If you specify 0, then accounts can be inactive indefinitely without being suspended.

Range: 0-32767
Default: 0
LockoutDurationInMinutes="number-of-minutes"

specifies the number of minutes that an internal user must wait before trying to log in again after having been locked out because of excessive login failures (see NumFailuresForLockout).

Range: 1-231
Default: 60
NumFailuresForLockout="number-of-failures"

specifies the number of authentication failures after which an internal user's account will be locked out.

CAUTION:
If you specify 0, your system could become vulnerable to password guessing attacks.   [cautionend]
Range: 0-100
Default: 3

Previous Page | Next Page | Top of Page

Copyright © 2011 by SAS Institute Inc., Cary, NC, USA. All rights reserved.