Sun ONE logo     Previous     Contents     Index     Next     
Sun ONE Identity Server Programmer's Guide



Chapter 12   Identity Server Utilities


The Sun 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 Restore

The 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 the 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 the Identity Server data stored in the Directory Server.



Backup Script

Following is the script used for backing up data. The utility is named am2bak and can be found in the <identity_server_root>/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:

  • ./am2bak [ -v | --verbose ] [ -k | --backup <backup-name> ] [ -l | --location <location> ] [[-c | --config] | [-b | --debug] | [-g | --log] | [-t | --cert] | [-d | --ds] | [-a | --all]]*

  • ./am2bak -h | --help

  • ./am2bak -n | --version

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 <identity_server_root>/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

  1. Login as root.

    The user running this script must have root access.

  2. 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:

      • <identity_server_root>/SUNWam/config/

      • <identity_server_root>/SUNWam/locale/

      • <identity_server_root>/SUNWam/servers/httpacl

      • <identity_server_root>/SUNWam/lib/*.properties (Java property files)

      • <identity_server_root>/SUNWam/bin/amserver.<instance-name>

      • <identity_server_root>/SUNWam/servers/https-<all_instances>

      • <identity_server_root>/SUNWam/servers/web-apps-<all_instances>

      • <identity_server_root>/SUNWam/web-apps/services/WEB-INF/config

      • <identity_server_root>/SUNWam/web-apps/services/config

      • <identity_server_root>/SUNWam/web-apps/applications/WEB-INF/classes

      • <identity_server_root>/SUNWam/web-apps/applications/console

      • /etc/rc3.d/K55amserver.<all_instances>

      • /etc/rc3.d/S55amserver.<all_instances>

      • <directory_server_root>/slapd-<host>/config/schema/

      • <directory_server_root>/slapd-<host>/config/slapd-collations.conf

      • <directory_server_root>/slapd-<host>/config/dse.ldif

    • Log And Debug Files:

      • var/opt/SUNWam/logs (Identity Server log files)

      • var/opt/SUNWam/install (Identity Server installation log files)

      • var/opt/SUNWam/debug (Identity Server debug files)

    • Certificates:

      • <identity_server_root>/SUNWam/servers/alias

      • <directory_server_root>/alias

    The script will also backup the following Microsoft® Windows 2000 operating system files:

    • Configuration and Customization Files:

      • <identity_server_root>/web-apps/services/WEB-INF/config/*

      • <identity_server_root>/locale/*

      • <identity_server_root>/web-apps/applications/WEB-INF/classes/*.properties (java property files)

      • <identity_server_root>/servers/https-<host>/config/jvm12.conf

      • <identity_server_root>/servers/https-<host>/config/magnus.conf

      • <identity_server_root>/servers/https-<host>/config/obj.conf

      • <directory_server_root>/slapd-<host>/config/schema/*.ldif

      • <directory_server_root>/slapd-<host>/config/slapd-collations.conf

      • <directory_server_root>/slapd-<host>/config/dse.ldif

    • Log And Debug Files:

      • var/opt/logs (Identity Server log files)

      • var/opt/debug (Identity Server debug files)

    • Certificates:

      • <identity_server_root>/servers/alias

      • <identity_server_root>/alias


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 <identity_server_root>/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:

  • ./bak2am [ -v | --verbose ] -z | --gzip <tar.gz-file> or -t | --tar <tar-file>

  • ./bak2am -h | --help

  • ./bak2am -n | --version

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 <identity_server_root>/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 <identity_server_root>/backup directory.

  • --help — accesses the script's help feature.

  • --version — prints the version of the backup script being used to the screen.


Restore Procedure

  1. Login as root.

    The user running this script must have root access.

  2. Untar the input tar file.

    This was generated when the backup script was run.



Utility API

The utilities package is called com.iplanet.am.util. It contains utility programs that can be used by external applications accessing Identity Server. The API include:

  • StatsListener

  • AdminUtils

  • Debug

  • Locale

  • Stats

  • SystemProperties

  • ThreadPool


    Note The Identity Server Javadocs can be accessed from any browser by copying the complete <identity_server_root>/SUNWam/docs/ directory into the <identity_server_root>/SUNWam/public_html directory and pointing the browser to http://<server_name.domain_name>:<port>/docs/index.html.



API Summary

Following is a summary of the utility API and their functions.


AMPasswordUtil

The AMPasswordUtil interface can be used to encrypt and decrypt passwords.


AdminUtils

This class contains the methods used to retrieve TopLevelAdmin information. The information comes from the server configuration file (serverconfig.xml).


Debug

Debug allows an interface to file debug and exception information in a uniform format. It supports different levels of filing debug 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.


Note

Debugging is an intensive operation and may hurt performance when abused. Java evaluates the arguments to message() and warning() even when debugging is turned off. It is recommended that the debug state be checked before invoking any message() or warning() methods to avoid unnecessary argument evaluation and to maximize application performance.



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 brand 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.


Previous     Contents     Index     Next     
Copyright 2002   Sun Microsystems, Inc. All rights reserved.

Last Updated December 02, 2002