| Sun ONE Identity Server Customization and API Guide |
Chapter 12
Identity Server UtilitiesSun™ ONE Identity Server provides scripts to backup and restore data as well as application programming interfaces (API) that are used by the server itself or by external applications. This chapter explains the scripts and the API. It contains the following sections:
Backup And RestoreThe Backup and Restore function of Identity Server allows businesses to keep their data safe by backing it to up and recovering it following an unexpected loss. Backed-up information includes all configuration, customization and identity data that has been modified or added since the initial installation of Identity Server. Log and debug files are also backed up. (Identity Server will not backup anything that remains unchanged from the installation state.)
The Restore function re-configures a freshly installed Identity Server to a former state, reflected by the data that was last backed up. It restores all the configuration, customization and identity data that was last backed up as well as the log and debug files. Both the Backup and Restore functions are initiated through the use of scripts provided with Identity Server.
Note
The backup and restore functions are performed on Identity Server data stored in Directory Server. This includes identity data as well as Identity Server customization data.
Backup Script
Following is the script used for backing up data. The utility is named am2bak and can be found in the IdentityServer_base/SUNWam/bin directory. am2bak takes command-line parameters and creates a backup.inf file containing information pertinent to the backup. A tar file is then created consisting of all the data.
Usage
The script is:
The options are defined as:
- -v | --verbose — runs the script in verbose mode.
- -k | --backup backup-name — defines the name of the backup file. The default filename is ambak.
- -l | --location location — defines the location of the backup file. The default is IdentityServer_base/backup.
- -c | --config — confines the backup to only configuration files. This also includes the service configuration data (updated service schema files and the service configurations for various organizations).
- -b | --debug — confines the backup to only debug files.
- -g | --log — confines the backup to only log files.
- -t | --cert — confines the backup to only the certification database.
- -d | --ds — confines the backup to the Directory Server.
- -a | --all — defines a complete backup of the Identity Server. This is the default option.
- --help — accesses the script’s help feature.
- --version — prints the version of the backup script being used to the screen.
Backup Procedure
- Login as root.
The user running this script must have root access.
- Run the script ensuring that the correct path is used, if necessary.
The script will backup the following Solaris™ Operating Environment files:
- Configuration and Customization Files:
- /etc/opt/SUNWam/config
- IdentityServer_base/SUNWam/locale/
- IdentityServer_base/SUNWam/servers/httpacl
- IdentityServer_base/SUNWam/lib/*.properties (Java property files)
- IdentityServer_base/SUNWam/bin/amserver.instance-name
- IdentityServer_base/SUNWam/web-apps/services/WEB-INF/config
- IdentityServer_base/SUNWam/web-apps/services/config
- IdentityServer_base/SUNWam/web-apps/applications/WEB-INF/classes
- IdentityServer_base/SUNWam/web-apps/applications/console
- /etc/rc3.d/K03amserver.all_instances
- /etc/rc3.d/S86amserver.all_instances
- DirectoryServer_install_directory/slapd-host/config/schema/
- DirectoryServer_install_directory/slapd-host/config/dse.ldif
- Log And Debug Files:
- Certificates:
- Configuration and Customization Files:
- IdentityServer_base/web-apps/services/WEB-INF/config/*
- IdentityServer_base/locale/*
- IdentityServer_base/web-apps/applications/WEB-INF/classes/*.properties (Java property files)
- IdentityServer_base/servers/https-host/config/jvm12.conf
- IdentityServer_base/servers/https-host/config/magnus.conf
- IdentityServer_base/servers/https-host/config/obj.conf
- DirectoryServer_install_directory/slapd-host/config/schema/*.ldif
- DirectoryServer_install_directory/slapd-host/config/dse.ldif
- Log And Debug Files:
- Certificates:
- Application Server IdentityServer_base/config/server.xml
- Application Server IdentityServer_base/config/server.policy
- Application Server IdentityServer_base/applications/j2ee-modules/
- Application Server IdentityServer_base/applications/j2ee-modules/
The script will backup the following files for BEA WebLogic:
- weblogic-install-dir/config/weblogic_domain>/startWebLogic.sh
- weblogic-install-dir/config/weblogic_domain/startManagedWebLogic.sh
- weblogic-install-dir/config/weblogic_domain/.java.login.config
- weblogic-install-dir/config/weblogic_domain/config.xml
- weblogic-install-dir/config/weblogic_domain/applications/
The script will backup the following files for IBM WebSphere:
- Websphere-install-dir/Websphere/Appserver/bin/admin.config
- Websphere-install-dir/Websphere/Appserver/bin/setupCmdLine.sh
- Websphere-install-dir/Websphere/Appserver/installedApps/
The script will backup the following files for Sun ONE Web Server:
- IdentityServer_base/SUNWam/servers/httpacl
- IdentityServer_base/SUNWam/lib/*.properties
- IdentityServer_base/SUNWam/bin/amserver.instance_name
- IdentityServer_base/SUNWam/web-apps/services/WEB-INF/config
- IdentityServer_base/SUNWam/web-apps/services/config
- IdentityServer_base/SUNWam/web-apps/applications/WEB-INF/classes
- IdentityServer_base/SUNWam/web-apps/applications/console
The script will backup the following common files for all containers:
- /etc/opt/SUNWam/config
- IdentityServer_base/SUNWam/locale
- IdentityServer_base/SUNWam/lib/.properties
- IdentityServer_base/SUNWam/bin/amserver.instance-name
- /etc/rc3.d/K03amserver.all_instances
- /etc/rc3.d/S86amserver.all_instances
- DirectoryServer_install_directory/slapd-host/config/schema
- DirectoryServer_install_directory/slapd-host/config/dse.ldif
Restore Script
Following is the script used for restoring backed-up data to a freshly reinstalled Identity Server. The utility is named bak2am and can be found in the IdentityServer_base/SUNWam/bin directory. bak2am takes the backup file name as a command-line parameters, reads the backup.inf file, untars the data file and performs the restoration accordingly.
Note
The Restore script will stop the Identity Server if it is running when the script is activated.
Usage
The script is:
The options are defined as:
- -v | --verbose — runs the script in verbose mode.
- -z | --gzip tar.gz file-name — defines the location of a gzipped data backup tar file. A full path name must be used if the file is not located in the default IdentityServer_base/backup directory.
- -t | --tar tar-file — defines the location of a data backup tar file. A full path name must be used if the file is not located in the default IdentityServer_base/backup directory.
- --help — accesses the script’s help feature.
- --version — prints the version of the backup script being used to the screen.
Restore Procedure
Utility APIThe utilities package is called com.iplanet.am.util. It contains utility programs that can be used by external applications accessing Identity Server. Following is a summary of the utility API and their functions.
AdminUtils
This class contains the methods used to retrieve TopLevelAdmin DN and password. The information comes from the server configuration file, serverconfig.xml, located in /IdentityServer_base/SUNWam/config/ums.
AMClientDetector
The AMClientDetector interface executes the Client Detection Class configured in the Client Detection Service to get the client type.
AMPasswordUtil
The AMPasswordUtil interface has two purposes:
- Encrypting and decrypting any string.
- Encrypting and decrypting special user passwords such as the password for dsameuser or proxy user.
Note
Any remote application using this utility should have the value of the AMConfig property am.encryption.pwd copied to a properties file on the client side. This value is generated at installation time and stored in /IdentityServer_base/SUNWam/lib/AMConfig.properties. More information on this property can be found in the Encryption section of the Appendix A, "AMConfig.properties File."
Debug
Debug allows an interface to file debug and exception information in a uniform format. It supports different levels of information (in the ascending order): OFF, ERROR, WARNING, MESSAGE and ON. A given debug level is enabled if it is set to at least that level. For example, if the debug state is ERROR, only errors will be filed. If the debug state is WARNING, only errors and warnings will be filed. If the debug state is MESSAGE, everything will be filed. MESSAGE and ON are the same level except MESSAGE writes to a file, whereas ON writes to System.out.
Locale
This class is a utility that provides the functionality for applications and services to internationalize their messages.
SystemProperties
This class provides functionality that allows single-point-of-access to all related system properties. First, the class tries to find AMConfig.class, and then a file, AMConfig.properties, in the CLASSPATH accessible to this code. The class takes precedence over the flat file. If multiple servers are running, each may have their own configuration file. The naming convention for such scenarios is AMConfig_serverName.
ThreadPool
ThreadPool is a generic thread pool that manages and recycles threads instead of creating them when a task needs to be run on a different thread. Thread pooling saves the virtual machine the work of creating new threads for every short-lived task. In addition, it minimizes the overhead associated with getting a thread started and cleaning it up after it dies. By creating a pool of threads, a single thread from the pool can be reused any number of times for different tasks. This reduces response time because a thread is already constructed and started and is simply waiting for its next task.
Another characteristic of this thread pool is that it is fixed in size at the time of construction. All the threads are started, and then each goes into a wait state until a task is assigned to it. If all the threads in the pool are currently assigned a task, the pool is empty and new requests (tasks) will have to wait before being scheduled to run. This is a way to put an upper bound on the amount of resources any pool can use up. In the future, this class may be enhanced to provide support growing the size of the pool at runtime to facilitate dynamic tuning.
Password API Plug-InsThe Password API plug-ins can be used to integrate password functions into applications. They can be used to generate new passwords as well as notify users when their password has been changed. These interfaces are PasswordGenerator and NotifyPassword, respectively. They can be found in the com.sun.identity.password.plugins package.
There are samples (which include sample code) for these API that can be accessed from the Identity Server installation. They are located in IdentityServer_base/SUNWam/samples/console. They include:
Notify Password Sample
This sample details how to build a plug-in in which an administrator can define their own method of notification when a user has reset a password. Instructions for this sample are in the Readme.txt or Readme.html file located in IdentityServer_base/SUNWam/samples/console/NotifyPassword.
Password Generator Sample
This sample details how to build a plug-in in which an administrator can define their own method of randon password generation when a user’s password is reset using the Password Reset Service. Instructions for this sample are in the Readme.txt or Readme.html file located in IdentityServer_base/SUNWam/samples/console/PasswordGenerator.
