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:
  • the names and locations of the adminUsers.txt and trustedUsers.txt files
  • the number of threads that are allowed to run concurrently on the SAS Metadata Server (contingent on the number of available processors)
  • the e-mail addresses to which alert e-mails are to be sent
  • journaling options
  • the location, the libref, and the engine used by the repository manager
  • policies regarding password assignment and management for internal users
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.
The file can contain the following XML elements:
<OMA>
specifies options for the metadata server. See <OMA> Options.
<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 SAS Internal Authentication in SAS Intelligence Platform: Security Administration Guide.
The following topics provide details for each omaconfig.xml option.

<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 in the event of a metadata server backup error, a metadata server recovery error, or an error that prevents the repository data sets from being updated from the journal.
To specify more than one address, enclose each address in single quotation marks, place a blank space between each address, and enclose the list in parentheses. For example: "('Bill@mycompany.com' 'Susan@mycompany.com')"
Interaction For the ALERTEMAIL 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. If your e-mail server requires authentication, the appropriate information must be provided in EMAILAUTHPROTOCOL, EMAILID and EMAILPASSWORD. See Options for the Metadata Server Invocation Command.
Tip If you modify any of the e-mail options, be sure to test metadata server e-mail alerts. See Testing E-mail Alerts for the SAS Metadata Server.
See Managing Alert E-mail Options for the SAS Metadata Server for more information.
ALERTEMAILTEST="text"
enables you to verify that the ALERTEMAIL option is set correctly. ALERTEMAILTEST is a temporary omaconfig.xml option that causes a test message to be sent at server start up in order to verify that the e-mail addresses specified in the ALERTEMAIL option 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 text string with this option. Using the option without a text string can also prevent the e-mail from being sent.
Note In SAS 9.3 and later releases, the Send Test Message button in SAS Management Console is the preferred method for testing alert e-mails. This feature enables you to test alert e-mails without stopping the metadata server. The button is located on the Active Server Properties dialog box in the Metadata Manager plug-in. See Testing E-mail Alerts for the SAS Metadata Server.
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.
JOURNALPATH="path-and-filename"
specifies a location to create the journal file if JOURNALTYPE="SINGLE" has been specified. (If JOURNALTYPE is set to NONE or ROLL_FORWARD, then the JOURNALPATH option is ignored.)
Note: The settings JOURNALTYPE="SINGLE" and JOURNALTYPE="NONE" are not recommended.
When specifying a location, keep these things in mind:
  • For consistency, we recommend that you specify the filename MetadataServerJournal.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.
  • 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 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.
Default If you specify JOURNALTYPE="SINGLE" but you do not specify a JOURNALPATH, then the journal is created in SAS-configuration-directory/Lev1/SASMeta/MetadataServer/Journal/MetadataServerJournal.dat.
Interaction This option is ignored if OMA JOURNALTYPE is set to NONE or ROLL_FORWARD.
JOURNALSIZE="number-of-bytes"
specifies a size, in bytes, for the journal file if JOURNALTYPE="SINGLE" has been specified. (If JOURNALTYPE is set to NONE or ROLL_FORWARD, then the JOURNALSIZE option is ignored.)
Note: The settings JOURNALTYPE="SINGLE" and JOURNALTYPE="NONE" are not recommended.
The space that you assign is reserved in the file system and is unavailable to other processes, whether the journal file is full or not. Journal entries are appended to the file until the file grows to the size that is specified. When the file reaches the specified size, subsequent journal entries overwrite previously written entries starting at the beginning of the file.
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.
Default If you specify JOURNALTYPE="SINGLE" but you do not specify a JOURNALSIZE, then the default size is used, as follows: 200MB on 32–bit machines and z/OS machines, and 500MB on 64–bit machines.
Interaction This option is ignored if OMA JOURNALTYPE is set to NONE or ROLL_FORWARD.
JOURNALTYPE="NONE | SINGLE | ROLL_FORWARD"
specifies whether metadata server journaling is enabled and, if so, which type of journal file is created. When journaling is enabled, access is returned to clients as soon as the metadata updates are written to the in-memory database and the journal file. The more time-consuming updates to the repository data sets are performed later in the background. If the metadata server fails before the update process has applied all of the updates from the journal file, the server recovers the updates from the journal file when it is restarted.
You can specify one of the following journal types:
NONE (Not recommended) disables the journaling feature so that no journal file is created. The JOURNALPATH and JOURNALSIZE options are ignored. The roll-forward option is not available when the metadata server is recovered from a backup. In addition, the metadata server cannot be backed up while the server is in an ONLINE state. The server will pause itself to a READONLY state each time a backup is executed, and any update transactions that are issued during the backup will fail.
SINGLE (Not recommended) enables the journaling feature by creating a single, circular journal file of a fixed size at the location that is specified in JOURNALPATH. Journal entries are appended to the file until the file grows to the size that is specified in JOURNALSIZE. When the file reaches the JOURNALSIZE limit, subsequent journal entries overwrite previously written entries starting at the beginning of the file. The roll-forward recovery option is not supported because there is no guarantee that all transactions that occurred since the last backup will still be available when a recovery is executed.
ROLL_FORWARD enables the journaling feature by creating a linear journal file that permanently stores all transactions that have occurred since the most recent backup. The journal file is written to the same location as the associated backup files. Each time a new backup is executed, journaling stops and a new journal file is started in the new backup location. The JOURNALPATH and JOURNALSIZE options are ignored. If ROLL_FORWARD is specified, the roll-forward option is available when the metadata server is recovered from a backup. If you change the option setting to ROLL_FORWARD from NONE or SINGLE, a metadata server backup is automatically performed when the server is restarted.
Default The SAS Deployment Wizard sets this option to ROLL_FORWARD during installation or during migration from SAS 9.1.3 or 9.2.
Interaction If ROLL_FORWARD or NONE is specified, then JOURNALPATH and JOURNALSIZE are ignored.
Tip 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.
See Configuring Metadata Server Journaling
CAUTION:
If you want to be able to use the roll-forward option in the event of a metadata server recovery, then make sure that a JOURNALTYPE of ROLL_FORWARD is specified.
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 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.
The initial setting for this parameter is 1.
Notes 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.
For a few solutions desktop clients (for example, SAS Model Manager, SAS Enterprise Miner, and SAS Forecast Studio), the ability to store credentials in client-side connection profiles is instead controlled by the Policy.AllowClientPasswordStorage property. To access this property, open the Plug-ins tab of SAS Management Console and navigate to Application Managementthen selectConfiguration Managerthen selectSAS Application Infrastructurethen selectSettingsthen selectPoliciesthen selectAllow client password storage.
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.
The initial setting for this parameter is SAS002.
Default If no value is specified for this parameter and SAS/SECURE is not installed, the SAS002 encoding method is used. If no value is specified for this parameter and SAS/SECURE is installed, the SAS003 encoding method is used.
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.
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.
The initial setting for this parameter is SAS002.
Default If no value is specified for this parameter and SAS/SECURE is not installed, the SAS002 encoding method is used. If no value is specified for this parameter and SAS/SECURE is installed, the SAS003 encoding method is used.
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.
Default 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 start-up 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 SAS Internal Authentication in 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.
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.
Default 0
Range 0–1440
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.
Default 0
Range 0–32767
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.
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.
Default T
Interaction This option is valid only if Expiration Days is greater than 0.
MinLength="number-of-bytes"
specifies the minimum allowed length for the passwords of internal users.
Default 6
Range 1–32
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.
Default 5
Range 0–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.
Default 0
Range 0–32767
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="number-of-failures".)
Default 60
Range 1–231
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.
Default 3
Range 0–100
Copyright © SAS Institute Inc. All rights reserved.