Sun Java System Access Manager 7 2005Q4 Administration Guide

Part IV Command Line Reference

This is the Command Line Reference, part four of the Sun Java System Access Manager 7 2005Q4 Administration Guide.

All of the command line tools described in this section can be found in the following default locations:

AccessManager-base/SUNWam/bin (Solairs)
AccessManager-base/identity/bin (Linux)

This section contains the following chapters:

Chapter 14 The amadmin Command Line Tool

This chapter provides information on the amadmin command line tool.

The amadmin Command Line Executable

The primary purposes of the command line executable amadmin is to load XML service files into the data store and to perform batch administrative tasks on the DIT. amadmin can be found in AccessManager-base/SUNWam/bin and is used to:

Load XML service files - Administrators load services into Access Manager that use the XML service file format defined in the sms.dtd. All services must be loaded using amadmin; they cannot be imported through the Access Manager console.

Note –

XML service files are stored in the data store as static blobs of XML data that is referenced by Access Manager. This information is not used by Directory Server, which only understands LDAP.

Perform batch updates of identity objects to the DIT - Administrators can perform batch updates to the Directory Server DIT using the batch processing XML file format defined in the amadmin.dtd. For example, if an administrator wants to create 10 organizations, 1000 users, and 100 groups, it can be done in one attempt by putting the requests in one or more batch processing XML files and loading them using amadmin.

Note –

amadmin only supports a subset of features that the Access Manager console supports and is not intended as a replacement. It is recommended that the console be used for small administrative tasks while amadmin is used for larger administrative tasks.

The amadmin Syntax

There are a number of structural rules that must be followed in order to use amadmin. The generic syntaxes for using the tool are:

amadmin -u | --runasdn dnname -w | --password password [-l | --locale localename] [[-v | --verbose] | [-d |--debug]] -t | --data xmlfile1 [ xmlfile2 ...]
amadmin -u | --runasdn dnname -w | --password password [-l | --locale localename] [[-v | --verbose] | [-d | --debug]] -s | --schema xmlfile1 [xmlfile2 ...]
amadmin -u | --runasdn dnname -w | --password password [-l | --locale localename] [[-v | --verbose] | [-d | --debug]] -r | --deleteService serviceName1 [serviceName2 ...]
amadmin -u | --runasdn dnname -w | --password password or -f | --passwordfile passwordfile [-c | --continue] [-l | --locale localename] [[-v | --verbose] | [-d | --debug]] -m | --session servername pattern
amadmin -h | --help
amadmin -n | --version
amadmin -u | --runasdn dnname -w | --password password or - f |--passwordfile passwordfile [-l | --locale localename] [[-v | --verbose] | [-d] |--debug]] -a |--addAttributes serviceName schemaType xmlfile[xmlfile2 ] ...

Note –

Two hyphens must be entered exactly as shown in the syntax.

amadmin Options

Following are definitions of the amadmin command line parameter options:

--runasdn (-u)

--runasdn is used to authenticate the user to the LDAP server. The argument is a value equal to that of the Distinguished Name (DN) of the user authorized to run amadmin; for example

--runasdn uid=amAdmin,ou=People,o=iplanet.com,o=isp .

The DN can also be formatted by inserting spaces between the domain components and double quoting the entire DN such as: --runasdn "uid=amAdmin, ou=People, o=iplanet.com, o=isp".

--password (-w)

--password is a mandatory option and takes a value equal to that of the password of the DN specified with the --runasdn option.

--locale (-l)

--locale is an option that takes a value equal to that of the name of the locale. This option can be used for the customization of the message language. If not provided, the default locale, en_US, is used.

--continue (-c)

--continue is an option that will continue to process the XML files even if there are errors. For example, if there are three XML files to be loaded at the same time, and the first XML file fails, amadmin will continue to load the remaining files. The continue option only applies to separate requests.

--session (-m)

--session (-m) is an option to manage the sessions, or to display the current sessions. When specifying --runasdn , it must be the same as the DN for the super user in AMConfig.properties , or just ID for the top-level admin user.

The following example will display all sessions for a particular service host name,:

amadmin -u uid=amadmin,ou=people,dc=iplanet,dc=com 
-v  -w 12345678 -m http://sun.com:58080

The following example will display a particular user’s session:

amadmin -u uid=amadmin,ou=people,dc=iplanet,dc=com -v 
 -w 12345678 -m http://sun.com:58080 username

You can terminate a session by entering the corresponding index number, or enter multiple index numbers (with spaces) to terminate multiple sessions.

While using the following option:

amadmin -m | --session servername pattern

The pattern may be a wildcard (*). If this pattern is using a wildcard (*), it has to be escaped with a meta character (\\) from the shell.

--debug (-d)

--debug is an option that will write messages to the amAdmin file created under the /var/opt/SUNWam/debug directory. These messages are technically-detailed but not i18n-compliant. To generate amadmin operation logs, when logging to database, the classpath for the database driver needs to be added manually. For example, add the following lines when logging to mysql in amadmin:

CLASSPATH=$CLASSPATH:/opt/IS61/SUNWam/lib/mysql-connector-java-3.0.6-stable-bin.jar
export CLASSPATH

--verbose (-v)

--verbose is an option that prints to the screen the overall progress of the amadmin command. It does not print to a file the detailed information. Messages output to the command line are i18n- compliant.

--data (-t)

--data is an option that takes as its value the name of the batch processing XML file being imported. One or more XML files can be specified. This XML file can create, delete and read various directory objects as well as register and unregister services. .

--schema (-s)

--schema is an option that loads the attributes of an Access Manager service into the Directory Server. It takes as an argument an XML service file in which the service attributes are defined. This XML service file is based on the sms.dtd . One or more XML files can be specified.

Note –

Either the --data or --schema option must be specified, depending on whether configuring batch updates to the DIT, or loading service schema and configuration data.

--deleteservice (-r)

--deleteservice is an option for deleting a service and its schema only.

--serviceName

--serviceName is an option that takes a value equal to the service name which is defined under the Service name=... tag of an XML service file. This portion is displayed in --serviceName.

Example 14–1 Portion of `sampleMailService.xml`

...
<ServicesConfiguration>
    <Service name="sampleMailService" version="1.0">
        <Schema
 serviceHierarchy="/other.configuration/sampleMailService"
            i18nFileName="sampleMailService"
            i18nKey="iplanet-am-sample-mail-service-description">
...

--help (-h)

--help is an argument that displays the syntax for the amadmin command.

--version (-n)

--version is an argument that displays the utility name, product name, product version and legal notice.

Using amadmin for Federation Management

This section lists the parameters of amadmin for use with Federation Management. For more information on Federation Management, see the Access Manager Federation Management Guide.

Loading the Liberty meta compliance XML into Directory Server

amadmin -u|--runasdn <user’s DN>
-w|--password <password> or -f|--passwordfile <passwordfile>
-e|--entityname <entity name>
-g|--import <xmlfile>

--runasdn (-u)

The user’s DN

--password (-w)

The user’s password.

--passwordfile (-f)

The name of file that contains user’s password.

--entityname (-e)

The entity name. For example, http://www.example.com. An entity should belong to only one organization.

--import (-g)

The name of an XML file that contains the meta information. This file should adhere to Liberty meta specification and XSD.

Exporting an Entity to an XML File (Without XML Digital Signing)

amadmin -u|--runasdn <user’s DN>

-w|--password <password> or -f|--passwordfile <passwordfile>
-e|--entityname <entity name>
-o|--export <filename>

--runasdn (-u)

The user’s DN

--password (-w)

The user’s password.

--passwordfile (-f)

The name of file that contains user’s password.

--entityname (--e)

The name of Entity that resides in the Directory Server

--export (-o)

The name of the file to contain the XML of the entity. XML shall be Liberty meta XSD compliance.

Exporting an Entity to an XML File (With XML Digital Signing)

amadmin -u|--runasdn <user’s DN>
-w|--password <password> or -f|--passwordfile <passwordfile>
-e|--entityname <entity name>
-q|--exportwithsig <filename>

--runasdn (-u)

The user’s DN

--password (-w)

The user’s password.

--passwordfile (-f)

The name of file that contains user’s password.

--entityname (--e)

The name of Entity that resides in the Directory Server

--exportwithsig (-o)

The name of the file to contain the XML of the entity. This file is digitally signed. The XML must be Liberty meta XSD compliant.

Using amadmin for Resource Bundles

The following section shows the amadmin syntax for adding, locating and removing resource bundles.

Add resource bundle.

amadmin -u|--runasdn <user-dn> -w|--password <user-password>

-b|--addresourcebundle <name-of-resource-bundle>

-i|--resourcebundlefilename <resource-bundle-file-name>

[-R|--resourcelocale] <locale>

Get resource strings.

amadmin -u|--runasdn <user-dn> -w|--password <user-password>

-z|--getresourcestrings <name-of-resource-bundle>

[-R|--resourcelocale] <locale>

Remove resource bundle.

amadmin -u|--runasdn <user-dn> -w|--password <user-password>

-j|--deleteresourcebundle <name-of-resource-bundle>

[-R|--resourcelocale] <locale>

Chapter 15 The ampassword Command Line Tool

This chapter provides information on the amPassword command line tool and contains the following section:

The ampassword Command Line Executable

The ampassword Command Line Executable

Access Manager contains an ampassword utility under /opt/SUNWam/bin on SPARC systems and /opt/sun/Identity/bin on Linux systems. This utility allows you change the Directory Server password for the administrator or user.

To Run ampassword with Access Manager in SSL mode

Modify the serverconfig.xml file, located in the following directory:
AccessManager-base/SUNWam/config/

Change port the server attribute to the SSL port which Access Manager is running.

Change the type attribute to SSL.

For example:

<iPlanetDataAccessLayer>
<ServerGroup name="default" minConnPool="1" maxConnPool="10">
    <Server name="Server1" host="sun.com" port="636" type="SSL" />
    <User name="User1" type="proxy">
        <DirDN>
                 cn=puser,ou=DSAME Users,dc=iplanet,dc=com
        </DirDN>
        <DirPassword>
                  AQIC5wM2LY4Sfcy+AQBQxghVwhBE92i78cqf
         </DirPassword>
 </User> ...

ampassword only changes the password in Directory Server. You will have to manually change passwords in the ServerConfig.xml and all authentication templates for Access Manager.

Chapter 16 The bak2am Command Line Tool

This chapter provides information on the bak2am command line tool and contains the following section:

The bak2am Command Line Executable

The bak2am Command Line Executable

Access Manager contains an bak2am utility under AccessManager-base/SUNWam/bin. This utility performs a restore of the Access Manager components that were backed-up by the am2back utility.

The bak2am Syntax

The generic syntax for using the bak2am tool for the Solaris operating system is:

./bak2am [ -v | --verbose ] -z | --gzip tar.gz-file
./bak2am [ -v | --verbose ] -t | --tar tar-file
./bak2am -h | --help
./bak2am -n | --version

The generic syntax for using the bak2am tool for the Windows 2000 operating system is:

bak2am [ -v | --verbose ] -d | --directory directory-name

bak2am -h | --help
bak2am -n | --version

Note –

Two hyphens must be entered exactly as shown in the syntax.

bak2am Options

--gzip `backup-name`

--gzip specifies the full path and filename of the backup file in tar.gz format. By default, the path is AccessManager-base/backup . This option is for Solaris only.

--tar `backup-name`

--tar specifies the full path and filename of the backup file in tar format. By default, the path is AccessManager-base/backup . This option is for Solaris only.

--verbose

--verbose is used to run the backup utility in verbose mode.

--directory

--directory specifies the backup directory. By default, the path is AccessManager-base/backup. This option is for Windows 2000 only.

--help

--help is an argument that displays the syntax for the bak2am command.

--version

--version is an argument that displays the utility name, product name, product version and legal notice.

Chapter 17 The am2bak Command Line Tool

This chapter provides information on the am2bak command line tool.

The am2bak Command Line Executable

Access Manager contains an am2bak utility under AccessManager-base/SUNWam/bin. This utility performs a backup of either all or optional components of Access Manager. Directory Server must be running while taking the log backup.

The am2bak Syntax

The generic syntax for using the am2bak tool for the Solaris operating system 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 generic syntax for using the am2bak tool for the Windows 2000 operating system 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

Note –

Two hyphens must be entered exactly as shown in the syntax.

am2bak Options

--verbose (-v)

--verbose is used to run the backup utility in verbose mode.

--backup `backup-name (-k)`

--backup backup-name defines the name of the backup file. The default is ambak.

--location (-l)

--location specifies the directory location of the backup. The default location is AccessManager-base/backup.

--config (-c)

--config specifies backup only for configuration files.

--debug (-b)

--debug specifies backup only for debug files.

--log (-g)

--log specifies backup only for log files.

--cert (-t)

--cert specifies backup only for certificate database files.

--ds (-d)

--ds specifies backup only for the Directory Server.

--all (-a)

--all specifies a complete backup of the entire Access Manager.

--help (-h)

--help is an argument that displays the syntax for the am2bak command.

--version (-n)

--version is an argument that displays the utility name, product name, product version and legal notice.

To Run the Backup Procedure

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:
  - AccessManager-base/SUNWam/config/
    - AccessManager-base/SUNWam/locale/
    - AccessManager-base/SUNWam/servers/httpacl
    - AccessManager-base/SUNWam/lib/*.properties (Java property files)
    - AccessManager-base/SUNWam/bin/amserver. instance-name
    - AccessManager-base/SUNWam/servers/https- all_instances
    - AccessManager-base/SUNWam/servers/web-apps- all_instances
    - AccessManager-base/SUNWam/web-apps/services/WEB-INF/config
    - AccessManager-base/SUNWam/web-apps/services/config
    - AccessManager-base/SUNWam/web-apps/applications/WEB-INF/classes
    - AccessManager-base/SUNWam/web-apps/applications/console
    - /etc/rc3.d/K55amserver.all_instances
    - /etc/rc3.d/S55amserver.all_instances
    - DirectoryServer-base/slapd- host /config/schema/
    - DirectoryServer-base/slapd- host /config/slapd-collations.conf
    - Access Manager/slapd- host /config/dse.ldif
    Log And Debug Files:
    - var/opt/SUNWam/logs (Access Manager log files)
    - var/opt/SUNWam/install (Access Manager installation log files)
    - var/opt/SUNWam/debug (Access Manager debug files)
    Certificates:
    - Access Manager/SUNWam/servers/alias
    - Access Manager/alias
      
      The script will also backup the following Microsoft® Windows 2000 operating system files:
    Configuration and Customization Files:
    - AccessManager-base/web-apps/services/WEB-INF/config/*
    - AccessManager-base/locale/*
    - AccessManager-base/web-apps/applications/WEB-INF/classes/*.properties (java property files)
    - AccessManager-base/servers/https- host/config/jvm12.conf
    - AccessManager-base/servers/https- host/config/magnus.conf
    - AccessManager-base/servers/https- host/config/obj.conf
    - DirectoryServer-base/slapd-host/config/schema/*.ldif
    - DirectoryServer-base/slapd-host/config/slapd-collations.conf
    - DirectoryServer-base/slapd-host/config/dse.ldif
    Log And Debug Files:
    - var/opt/logs (Access Manager log files)
    - var/opt/debug (Access Manager debug files)
    Certificates:
    - AccessManager-base/servers/alias
    - AccessManager/alias

Chapter 18 The amserver Command Line Tool

This chapter provides information on the amserver command line tool. This chapter contains the following section:

The amserver Command Line Executable

The amserver Command Line Executable

The amserver command line executable starts and stops the amunixd and amsercuridd helpers, associated with Unix and SecurID authentication modules, respectively.

amserver Syntax

The generic syntax for the tools is:

./amserver { start | stop }

start

start is a command that starts the helper.

stop

stop is a command that stops the helper.

Chapter 19 The VerifyArchive Command Line Tool

This chapter provides information on the VerifyArchive command line tool and contains the following section:

The VerifyArchive Command Line Executable

The VerifyArchive Command Line Executable

The purpose of VerifyArchive is to verify the log archives. A log archive is a set of timestamped logs and their corresponding key stores (keystores contain the keys used to generate the MACs and the Digital Signatures which are used to detect tampering of the log files). Verification of an archive detects possible tampering and/or deletion of any file in the archive.

VerifyArchive extracts all of the archive sets, and all files belonging to each archive set, for a given logName. When executed, VerifyArchive searches each log record to for tampering If tampering is detected, it prints a message specifying which file and the number of the record that has been tampered with.

VerifyArchive also checks for any files that have been deleted from the archive set. If a deleted file is detected, it prints a message explaining that verification has failed. If no tampering or deleted files are detected, it returns a message explaining that the archive verification has been successfully completed.

Note –

An error may occur if you run amverifyarchive as a user without administrator privileges.

VerifyArchive Syntax

All of the parameters options are required. The syntax is as follows:

amverifyarchive -l logName -p path -u 
uname -w password

VerifyArchive Options

logName

logName refers to the name of the log which is to be verified (such as, amConsole, amAuthentication and so forth). VerifyArchive verifies the both the access and error logs for the given logName. For example, if amConsole is specified, the verifier verifies the amConsole.access and amConsole.error files. Alternatively, the logName can be specified as amConsole.access or amConsole.error to restrict the verification of those logs only.

path

path is the full directory path where the log files are stored.

uname

uname is the user id of the Access Manager administrator.

password

password is the password of the Access Manager adminstrator.

Chapter 20 The amsecuridd Helper

This chapter provides information on the amsecuiridd helper and contains the following section:

The amsecuridd Helper Command Line Executable

The Access Manager SecurID authentication module is implemented using the Security Dynamic ACE/Client C API and the amsecruidd helper, which communicates between the Access Manager SecurID authentication module and the SecurID Server. The SecurID authentication module invokes the amsecuridd daemon by opening a socket to localhost:57943 to listen for SecurID authentication requests.

Note –

57943 is the default port number. If this port number is already used, you can specify a different port number in the SecurID Helper Authentication Port attribute in the SecurID Authentication module. This port number must be unique accross all organizations.

Because the interface to amsecuridd is in clear text through stdin, only local host connections are permitted. amsecuridd uses the SecurID remote API (version 5.x) on the back end for data encryption.

The amsecuridd helper listens on port number 58943 (by default) to receive its configuration information. If this port is already used, you can change it in the securidHelper.ports attribute in the AMConfig.properties file (by default, located in AccessManager-base /SUNWam/config/). The securidHelp.ports attribute contains a space-separated list of the ports for each amsecuridd helper instance. Restart Access Manager once the changes to AMConfig.properties are saved.

Note –

A separate instance of amsecuridd should run for each organization that communicates with a separate ACE/Server (containing different sdconf.rec files).

amsecuridd Syntax

The syntax is as follows:

amsecuridd [-v] [-c portnum]

amsecuridd Options

verbose (-v)

Turns on verbose mode and logs to /var/opt/SUNWam/debug/securidd_client.debug .

configure portnumber (-c portnm)

Configures the listening port number. The default is 58943.

Running the amsecuridd helper

amsecuridd is located, by default, in AccessManager-base /SUNWam/share/bin. To run the helper on the default ports, enter the following command (without options):

./amsecuridd

To run the helper on non-default port, enter the following command:

./amsecuridd [-v] [-c portnm]

amsecuridd can also be run through the amserver command line utitility, but it will only run on the default ports.

Required Libraries

In order to run the helper, the following libraries are required (most can be found in the operating system in /usr/lib/):

libnsl.so.1
libthread.so.1
libc.so.1
libdl.so.1
libmp.so.2
librt.so.1
libaio.so.1
libmd5.so.1

Note –

Set LD_LIBRARY_PATH to AccessManager-base /Sunwam/lib/ to find libaceclnt.so.

Part IV Command Line Reference

Chapter 14 The amadmin Command Line Tool

The amadmin Command Line Executable

The amadmin Syntax

amadmin Options

--runasdn (-u)

--password (-w)

--locale (-l)

--continue (-c)

--session (-m)

--debug (-d)

--verbose (-v)

--data (-t)

--schema (-s)

--deleteservice (-r)

--serviceName

Example 14–1 Portion of sampleMailService.xml

--help (-h)

--version (-n)

Using amadmin for Federation Management

Loading the Liberty meta compliance XML into Directory Server

--runasdn (-u)

--password (-w)

--passwordfile (-f)

--entityname (-e)

--import (-g)

Exporting an Entity to an XML File (Without XML Digital Signing)

--runasdn (-u)

--password (-w)

--passwordfile (-f)

--entityname (--e)

--export (-o)

Exporting an Entity to an XML File (With XML Digital Signing)

--runasdn (-u)

--password (-w)

--passwordfile (-f)

--entityname (--e)

--exportwithsig (-o)

Using amadmin for Resource Bundles

Add resource bundle.

Get resource strings.

Remove resource bundle.

Chapter 15 The ampassword Command Line Tool

The ampassword Command Line Executable

To Run ampassword with Access Manager in SSL mode

Chapter 16 The bak2am Command Line Tool

The bak2am Command Line Executable

The bak2am Syntax

bak2am Options

--gzip backup-name

--tar backup-name

--verbose

--directory

--help

--version

Chapter 17 The am2bak Command Line Tool

The am2bak Command Line Executable

The am2bak Syntax

am2bak Options

--verbose (-v)

--backup backup-name (-k)

--location (-l)

--config (-c)

--debug (-b)

--log (-g)

--cert (-t)

--ds (-d)

--all (-a)

--help (-h)

--version (-n)

To Run the Backup Procedure

Chapter 18 The amserver Command Line Tool

The amserver Command Line Executable

amserver Syntax

start

stop

Chapter 19 The VerifyArchive Command Line Tool

The VerifyArchive Command Line Executable

VerifyArchive Syntax

VerifyArchive Options

Example 14–1 Portion of `sampleMailService.xml`

--gzip `backup-name`

--tar `backup-name`

--backup `backup-name (-k)`