The migrateEAR utility migrates changes made to
console users and groups in the admin-authz.xml and naming-authz.xml files
into the Tivoli® Access Manager object space.
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
Syntax
migrateEAR
-j fully_qualified_filename
-c pdPerm.properties_file_location
-a Tivoli_Access_Manager_administrator_ID
-p Tivoli_Access_Manager_administrator_password
-w WebSphere_Application_Server_administrator_user_name
-d user_registry_domain_suffix
[-r root_objectspace_name]
[-t ssl_timeout]
[-z role_mapping_location]
Syntax
migrateEAR -profile_name default
-j fully_qualified_filename
-a Tivoli_Access_Manager_administrator_ID
-p Tivoli_Access_Manager_administrator_password
-w WebSphere_Application_Server_administrator_user_name
-d user_registry_domain_suffix
-c PdPerm.properties_file_location
[-z role_mapping_location]
Attention: - The -j parameter defaults to the file: profile_root/config/cells/cell_name/admin-authz.html
- The -c parameter defaults to: file:profile_root/etc/pd/PdPerm.properties.
The output of the utility is logged in the pdwas_migrate.log file.
The pdwas_migrate.log file is created in the profile_root/logs directory.
- The -profile_name parameter is optional and defaults
to the default profile name.
Parameters
Attention: In the following parameters, use the absolute path
instead of a variable.
- -aTivoli_Access_Manager_administrator_ID
- The administrative user identifier. The administrative user must
have the privileges required to create users, objects, and access
control lists (ACLs). For example, -a sec_master.
This
parameter is optional. When the parameter is not specified, you are
prompted to supply it at run time.
- -c PdPerm.properties_file_location
- The Uniform Resource Indicator (URI) location of the PdPerm.properties file
that is configured by the pdwascfg utility. When WebSphere Application
Server is installed in the default location, the URI is:
![[Solaris]](../images/solaris.gif)
![[Linux]](../images/linux.gif)
file:/opt/IBM/WebSphere/AppServer/java/jre/PdPerm.properties
file:/usr/IBM/WebSphere/AppServer/java/jre/PdPerm.properties
file:/"C:/Program Files/IBM/WebSphere/AppServer/java/jre/PdPerm.properties”
- -d user_registry_domain_suffix
- The domain suffix for the user registry to use. For example, for
Lightweight Directory Access Protocol (LDAP) user registries, this
value is the domain suffix, such as: "o=ibm,c=us"
Windows platforms require that
the domain suffix is enclosed within quotes.
You can use the pdadmin
user show command to display the distinguished name (DN) for a
user.
- -j fully_qualified_pathname
- The fully qualified path and file name of the Java 2
Platform, Enterprise Edition application archive file ,admin-authz.xml or
the roles definitions file naming-authz.xml that is used
for a naming operation authorization. Optionally, this path can also
be a directory of an expanded enterprise application. For example,
when WebSphere Application Server is installed
in the default location, the path to the data files to migrate includes:
![[Solaris]](../images/solaris.gif)
![[Linux]](../images/linux.gif)
file:/opt/IBM/WebSphere/AppServer/profiles/profile_name/config/cells
/cell_name/admin-authz.xml
file:/usr/IBM/WebSphere/AppServer/profiles/profile_name/config/cells
/cell_name/admin-authz.xml
“C:/Program Files/IBM/WebSphere/AppServer/profiles/profile_name/config/cells
/cell_name/admin-authz.xml”
- -p Tivoli_Access_Manager_administrator_password
- The password for the Tivoli Access Manager administrative
user. The administrative user must have the privileges that are required
to create users, objects, and access control lists (ACLs). For example,
you can specify the password for the -a sec_master administrative
user as -p myPassword.
When this parameter is not specified,
the user is prompted to supply the password for the administrative
user name.
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
-r root_objectspace_name
- The space name of the root object. The value is the name of the
root of the protected object namespace hierarchy that is created for WebSphere Application Server policy data.
The
default value for the root object space is WebAppServer.
Set
the Tivoli Access Manager root object space name
by modifying the amwas.amjacc.template.properties file prior
to configuring the Java Authorization Contract for
Containers (JACC) provider for Tivoli Access
Manager for the first time. Use this option if the default object
space value is not used in the configuration of the Tivoli Access
Manager JACC provider for Tivoli Access Manager.
Do
not change the Tivoli Access Manager object space name after
the Tivoli Access Manager JACC provider is configured.
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
-t ssl_timeout
- The number of minutes for the Secure Sockets Layer (SSL) timeout.
This parameter is used to disconnect and reconnect the SSL context
between the Tivoli Access Manager authorization server
and the policy server before the default connection times out.
The
default is 60 minutes. The minimum value is 10 minutes.
The maximum value cannot exceed the Tivoli Access
Manager ssl-v3-timeout value. The default value for ssl-v3-timeout
is 120 minutes.
If you are not familiar with the administration
of this value, you can safely use the default value.
- -w WebSphere_Application_Server_administrator_user_name
- The user name that is configured in the WebSphere Application
Server security user registry field as the administrator. This value
matches the account that you created or imported in Creating the security administrative user for Tivoli Access Manager. Access permission
for this user is needed to create or update the Tivoli Access
Manager protected object space.
When the WebSphere Application
Server administrative user does not already exist in the protected
object space, it is created or imported. In this case, a random password
is generated for the user and the account is set to not valid.
Change this password to a known value and set the account to valid.
A
protected object and access control list (ACL) are created. The administrative
user is added to the pdwas-admin group with the following ACL attributes:
- T
- Traverse permission
- i
- Invoke permission
- WebAppServer
- You can overwrite the action group name. The default name is WebAppServer.
This action group name and the matching root object space can be overwritten
when the migration utility is run with the -r option.
- -z role_mapping_location
- The location where the role mapping is to be stored when migrating
administration applications. The default location is to place the
role mapping in the current directory structure, such as:
/WebAppServer/deployedResouces
Specifying
the -z option adds another directory level in which to store the role
mapping. For example, if you specify
-z Roles in
the migrateEAR utility, the role mapping is stored in the directory
structure as follows:
/WebAppServer/deployedResouces/Roles
Avoid trouble: If the -z option is
specified, you must manually update the value of the com.tivoli.pd.as.rbpf.RoleContainerName
property in the amwas.
node_name.amjacc.properties,
and amwas.
node_name.authztable.properties files
such that this value matches the value specified for the -z option.
You do not have to restart WebSphere Application Server
after updating the value of the com.tivoli.pd.as.rbpf.RoleContainerName
property
gotcha
Comments
This utility migrates security
policy information from deployment descriptors or enterprise archive
files to Tivoli Access Manager for WebSphere Application
Server. The script calls com.tivoli.pdwas.migrate.Migrate the Java class.
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
Before
invoking the script you must run the setupCmdLine.bat or the setupCmdLine.sh commands.
These files can be found in the %WAS_HOME%/bin directory.
Before you invoke
the script, you must run the setupCmdLine script from the Qshell
command line. You can find this file in the profile_root/bin directory,
where profile_root is your installation path. In a default
installation, profile_root is app_server_rootND.
![[IBM i]](../images/iseries.gif)
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
The script is dependent on finding the
correct environment variables for the location of prerequisite software.
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
![[z/OS]](../images/ngzos.gif)
The script calls Java code
with the following options:
- -Dpdwas.lang.home
- The directory that contains the native language support libraries
that are provided with the JACC provider for Tivoli Access
Manager. These libraries are located in a subdirectory under the JACC
provider for Tivoli Access Manager installation directory.
For example: -Dpdwas.lang.home=%PDWAS_HOME%\java\nls
- -cp %CLASSPATH% com.tivoli.pdwas.migrate.Migrate
- The CLASSPATH variable must be set correctly for your Java installation.
![[Windows]](../images/windows.gif)
Both the -j option and the
-c option can reference the %WAS_HOME% variable to determine where WebSphere Application Server is installed.
This information is used to:
- Build the full path name of the enterprise archive file.
- Build the full URI path name to the location of the PdPerm.properties file.
To enable a new user access to the administrative group
in WebSphere Application Server, it is recommended
that the user be added to the pdwas-admin group after JACC has been
enabled. You can enter the administrative primary ID (adminID) in
the group. This is required when the serverID is not the same as the
adminID.
The following is an example of this command:
pdadmin> group modify pdwas-admin add adminID
Return codes
The utility can return the
following exit status codes:
- 0
- The command completed successfully.
- 1
- The command failed.