Update Security Files after Exporting Users and Groups :: DataFlux® Data Management Server 2.7: Administrator's Guide

Introduction

Use the dftool utility to update local security files after you export users and groups from DataFlux Authentication Server to SAS Metadata Server. In the security files, the dftool utility replaces DataFlux Authentication Server IDs with SAS Metadata Server IDs. The update process ensures that the security files are synchronized with the SAS Metadata Server.

The dftool utility displays and logs all IDs that were replaced, and also displays and logs any DataFlux Authentication Server IDs that remain. IDs are replaced only if matching users or groups are found on the SAS Metadata Server.

Replacing or removing all DataFlux Authentication Server IDs ensures appropriate access to server resources.

After running dftool, a restart is required for DataFlux Data Management Server.

Prerequisites

The prerequisites for running the dftool utility are as follows:

As needed, install, update, configure, and start your SAS Metadata Server.
On DataFlux Authentication Server, make sure that all users and groups were successfully exported to SAS Metadata Server, as described in DataFlux Authentication Server: Administrator’s Guide, at http://support.sas.com/documentation/onlinedoc/dfauthserver/index.html.
Obtain login credentials that are recognized by SAS Metadata Server. The credentials must meet the following requirements:
- On SAS Metadata Server, the credentials must be granted the Read Metadata permission.
- On DataFlux Data Management Server, the credentials must have Read, Write, and Delete permissions for the following directories:
  dmserver-install-path\etc\security
  dmserver-install-path\var
  
  You can enter credentials on the command line when you run dftool, or you can enter default credentials into a configuration file, as described in Specify Default Credentials for Dftool.
If DataFlux Data Management Server runs in the UNIX operating environment, then set the environment variable TKERSA2_LIB_PATH as follows:
```
TKERSA2_LIB_PATH=/dmserver-install-path/SASHome/DataManagementServer/
   release-number/dmserver/lib/tkts export TKERSA2_LIB_PATH
```
Note: Your instance of the path shown above might contain an incorrect name for the release-number directory. This occurs when the server software upgrade process replaces the previous version of the software in the directory of the previous release. If you are uncertain about the current release of your software, check the dates on the files in the directory. You can change the name of the release-number directory without causing errors.
Configure the DataFlux Data Management Server to authenticate using SAS Metadata Server. Specifically, in the file dmserver-install-path\etc\app.cfg, the value of configuration option BASE/AUTH_SERVER_LOC needs to be the fully qualified network name of SAS Metadata Server. If you have a clustered SAS Metadata Server, then the network name needs to identify the cluster configuration file.
To generate a log file for dftool, the following configuration file must be present on the server host: dmserver-install-path\etc\dftool.log.xml. If DataFlux Data Management Server was recently upgraded, then the configuration file is installed with the name dftool.log.xml.new. This filename has to be changed before a log file can be generated by the dftool utility. The .new extension must be removed from the filename.

Run the Dftool Utility

Follow these steps to run the dftool utility:

Meet the prerequisites in the preceding topic.
Open a shell window on the host of DataFlux Data Management Server. Change to the following directory and enter the following command:
```
dmserver-install-path\bin> dftool dismigrtsec
```
Note: In certain Windows operating environments, you are required to open an Administrator: Command Prompt window. One way to open this window is to enter the following text in Search programs and files:
```
command prompt - Administrator
```
The dftool utility displays a prompt to enter alternate credentials for connecting to SAS Metadata Server. Select Enter to bypass the entry of alternative credentials.
The dftool utility displays its activities and exits. For further information about dftool processing, including the copying and renaming of security files, see Summary of Execution.
Examine the shell text or the log files to ensure that all IDs from DataFlux Authentication Server were replaced. Two log files are generated each time you run dftool: dftool.log and dftool_security.log. The log files are located in the directory dmserver-install-path\var. Dftool.log is the platform debug log file. Dftool_security.log is a summary log file that lists only the DataFlux Authentication Server IDs that were not matched and replaced by SAS Metadata Server IDs.

If no unmatched IDs from DataFlux Authentication Server remain, then the summary log file will be empty. If unmatched IDs are found, then the summary log file contains an entry in the following format for each affected security file:
```
unknown old ID:  'FF4ADD49C7599BA479FB9C13C742E8C0'
unknown old ID:  'FF4ADD49C7599BA479FB9C13C742E8C1'
Processed file:  'C:\Program Files\DataFlux\DMServer\2.7\bin\etc\security\users'
```
If the log files indicate that unmatched IDs remain, then consider running PROC ASExport again on your DataFlux Authentication Servers, as described in DataFlux Authentication Server 4.1 Administrator’s Guide, 2nd Edition. After the export, run dftool again on DataFlux Data Management Server.
If no unmatched DataFlux Authentication Server IDs are found (summary log file empty), then the cause might be one or more following:
- All IDs were previously replaced.
- Your credentials for running dftool do not have appropriate permission to read or display users and groups from the SAS Metadata Server.
- PROC ASExport did not run or did not run correctly. Examine the log files to see the users and groups that were exported to SAS Metadata Server.
If PROC ASExport indicates that all users and groups have been exported, unmatched IDs can still exist on DataFlux Data Management Server. To resolve this condition, verify that the unmatched users and groups are not present on your SAS Metadata Server or DataFlux Authentication Servers. Next, delete those users or groups from the security settings on your DataFlux Data Management Server, using the administrative interface in DataFlux Data Management Studio.
Restart DataFlux Data Management Server so that the server can read the new security files into memory.

Summary of Execution

The dftool utility runs as follows:

Open app.cfg to determine the network name of SAS Metadata Server, as specified by the option BASE/AUTH_SERVER_LOC. Also look for alternative credentials in the options BASE/AUTH_SERVER_USER and BASE/AUTH_SERVER_PASS.
Request from SAS Metadata Server the users and groups that were migrated from DataFlux Authentication Server. If no users or groups are returned, dftool exits.
Search the DataFlux Data Management Server security files for user and group IDs that were generated by DataFlux Authentication Server. If one is found, and if the associated user or group has a match on SAS Metadata Server, then copy and rename the security file. In the original security file, replace the old ID with the ID from SAS Metadata Server. Rename the file with a numeric suffix such as .001 or .012. The suffix indicates the number of times that the original security file has been replaced by previous runs of the dftool utility.

If an ID from DataFlux Authentication Server is found, and if a matching user and group is not found, then log the unmatched ID for that security file.

Specify Default Credentials for Dftool

Follow these steps to define default credentials that will be used by the dftool utility to connect to SAS Metadata Server. Default credentials are helpful if you are not running dftool with credentials that provide read metadata access on SAS Metadata Server.

Edit the file dmserver_install_path\etc\app.cfg.
Add or update the following configuration options:
```
BASE/AUTH_SERVER_USER=user-name
BASE/AUTH_SERVER_PASS=encrypted-password
```
Note: To encrypt a new password, use PROC PWENCODE, as described in Base SAS Procedures Guide.
Save and close the configuration file.
Run dftool again to pick up the changes in the configuration file.