About the Password Update Tool

The password update tool is intended for use with deployments of the SAS Intelligence Platform (release 9.1.3 or later, with SAS Web Report Studio release 2.1 or later). The tool automates part of the password update process for required accounts, providing an alternative to the manual instructions in step 4 of that process. If you need assistance using this tool, please contact a SAS technical support consultant.

Note: The HTML topic that is linked to above is in the Security Administration guide, which is available in PDF format from support.sas.com/913administration.

Note: You must have a JDK to use the password update tool (we recommend that you use JDK 1.4.1 or 1.4.2).

The password update tool works like this:

1. You provide these inputs to the tool:

   • The full paths to your site's 2 top-level locations for SAS Intelligence Platform configuration files (your configuration directory and your installation directory).

   • User ID and password information for each account that you are updating. You can provide these directly in the command line or by referencing a separate file. The passwords that you provide should be in clear text; the tool will encrypt the passwords for you.
     
     Note: If you run the tool without providing user ID and password information, the program generates a list all of the userID/password pairs that it discovers in your configuration files.

2. The tool passes each userID/new-password pair to the authentication provider for the SAS Metadata Server to verify that the new password corresponds to a valid account.

3. The tool encrypts the passwords and then uses its internal pwfile.xml file to locate and update all instances of the passwords in your configuration files.

4. The tool generates log and error files as specified by you.

Note: In a multi-machine deployment, you must run this tool on each machine where the configuration wizard has been run. You must have read and write access to the files that you are going to modify.

Installation

Extract the contents of the downloaded file into a temporary directory.

For Windows, the downloaded file is 913configpasswd01wn.zip. Use WinZip to unzip the downloaded file, which will result in the following files being extracted to the temporary directory:

913configpasswd01\PwFile.jar
913configpasswd01\PwFileDoc.htm

For UNIX, the downloaded file is 913configpasswd01ux.tar. Extract the contents of the downloaded file using the tar command, for example

$> tar -xf $HOME/913configpasswd01ux.tar

where $HOME is the location to where the tar file was downloaded. The tar command will extract the following files to the directory from where the tar command is executed:

913configpasswd01/PwFile.jar
913configpasswd01/PwFileDoc.htm

Syntax and Options for the Password Update Tool

A basic form of the command is:

The command line options are:

-sasHome path

specifies the top-level installation directory for the SAS Intelligence Platform. By default, the top level installation directory is drive: \Program Files\SAS on windows systems.

-sasConfig path

specifies the top-level configuration directory for the SAS Intelligence Platform. By default, the configuration directory is located in drive:\SAS on Windows systems and in installer's-home-directory/SAS on UNIX systems.

-configLevel directory

specifies the directory name of the configuration level. This is first element in the directory path that immediately follows the top level path (which is specified by -sasConfig). The default value is Lev1. This option enables you to replace the Lev1 part of a configuration path if your directory has a different name.

-userID user_identifier

specifies the user ID of the account that you are updating. To run the command for multiple accounts, use the -pwFile option instead. User IDs for Windows accounts must be qualified with a machine or Windows domain name.

-password password_value

specifies the new password for the account that you identified in -userID. Do not provide an encrypted password; the tool encrypts the passwords for you. If you specify a value for -userID and you do not specify a value for -password, you will be prompted for the password value.

-epassword encrypted_password_value

specifies the new password for the account that you identified in -userID. The tool assumes the password being provided is already encrypted and copies the value to the target files verbatim.

-pwFile filename

specifies the name of a file that contains account ID and password information (as an alternative to providing this information directly on the command line). You must use the -configPath option to specify the location of this file. This file should contain the userID and password for each required account that you want to update, for example:
userid="sastrust" password="new-password-for-sastrust"
userid="sassrv" password="new-password-for-sassrv"
userid="sasguest" epassword="new-encrypted-password-for-sasguest"
Windows IDs should be qualified with the machine or Windows domain name. For "password=", do not provide an encrypted password; the tool encrypts the passwords for you. However, for "epassword=", you provide an encrypted password which will be copied verbatim to the target files.

-configPath path

specifies the location of the optional pwfile.properties and -pwFile files.

-metadataServer server_name

specifies the host name or IP address of the computer that hosts the metadata server. This facilitates validation of the new passwords.

-metadataPort port_number

specifies the port number on which the metadata server listens for requests. This facilitates validation of the new passwords.

-noValidation

causes the tool to skip the step of connecting to the SAS Metadata Server and validating the new passwords to verify that they correspond to valid accounts.

-noPrompt

prevents prompting and causes default values to be used instead.

-verbose

causes the command settings to be printed to the log file.

-logFile filename

specifies a log file name. If -logFile is omitted, log messages go to standard output.

-errorFile filename

specifies an error file name. If -errorFile is omitted, error messages are printed to standard error.

-help

displays this information about the options.

Saving Options in a pwfile.properties File

As an alternative to specifying options on the command line, you can create a file named pwfile.properties to store your values for metadataServer, metadataPort, pwFile, sasHome, and sasConfig. Values that you specify on the command line override values that you store in the properties file. You must use the -configPath option on the command line to specify the location of your pwfile.properties file.

For example, if you create a C:\PWupdate\pwfile.properties file that contains these lines:

and you execute this command:

then the tool produces a list of your configuration files that contain passwords.

Note: If you use a backslash in the pwfile.properties file, you must also use the escape character, as illustrated in the example.

Usage Examples: Windows

For example, to update the password for the SAS Trusted User in the configuration files on a Windows machine, you could enter this command:

Or, to update the passwords for the SAS Trusted User, the SAS Guest User, and the SAS Administrator, you could create a file named C:\PWupdate\PWchanges.txt that contains these lines:

and then use this command:

Or, to update the same passwords and store options in a properties file, you could create a file named C:\PWupdate\pwfile.properties that contains these lines:

and then use this command:

To use encrypted passwords, you must first encrypt the password using a SAS program.  Suppose you wanted to encrypt the password "SASTrust1", you would submit the following SAS program: