Table Of Contents

Using the Command Line Interface (CLI)

About the CLI

Command Summary

Understanding Configuration Data

Using the Command-Line Interface

Command Reference

version

getdeployed

compile

deploy

validity

exportppf

crl_status

translate

replacecert

replacepkcs12key

replacekeyandcert

renamecert

renamehandler

setserverhostname

setserverport

sethttpport

sethttphostname

sethandlerloglevel

Using the Command Line Interface (CLI)

---

This chapter describes the ACE XML system command-line interface. It covers these topics:

•About the CLI

•Using the Command-Line Interface

•Command Reference

About the CLI

The ACE XML appliance includes a command-line interface (CLI) that enables you to perform many common administrative operations from the ACE XML Manager command line.

The capabilities provided by the CLI compose a subset of the functionality available in the ACE XML Manager web console, the interface for administering the system. The CLI is useful as an alternative to using the web console when you want to perform management operations quickly, particularly if already working in the ACE XML Manager web console environment.

More significantly, the CLI gives administrators a mechanism for executing administrative operations from scripts. Scripting CLI commands can significantly ease the process of deploying policies from a test environment to production.

Many of the commands in the CLI are intended to facilitate this process. For example, the CLI includes commands for compiling and deploying policies, renaming policy artifacts, and replacing certificates (since production security certificates normally differ from those used in a development or testing environment).

---

Note It's possible for a policy to be edited by a CLI command at the same time as a Manager user is editing the policy in the ACE XML Manager web console. The changes made by the CLI command are not immediately reflected in the policy as it appears in the ACE XML Manager web console. Console users must log out of the console and then log back in to see the effects of the command. In general, use care to avoid conflicts between multiple console users, including CLI users.

---

Command Summary

The following table provides an overview of the commands in the ACE XML Gateway CLI.

Command	Description
compile	Tags the head policy, compiles it, and places the result in the compiled policies directory.
crl_status	Reports the revoked security certificates known to the gateway.
deploy	Tags the working policy in the ACE XML Manager and deploys to a given ACE XML Gateway.
exportppf	Exports the current working policy to a named file.
getdeployed	Retrieves the ID of the deployed policy.
renamecert	Renames the specified certificate.
renamehandler	Renames the specified handler.
replacecert	Replaces the named certificate.
replacepkcs12key	Replaces the named key using a PKCS12 file.
replacekeyandcert	Replaces the named key using separate key and certificate files.
setserverhostname	Changes the hostname used to address the given back-end HTTP server.
setserverport	Changes the port number used to address the given back-end HTTP server.
sethttpport	Changes the port number for the given HTTP port object (used to listen for incoming requests).
sethttphostname	Changes the hostname for the given HTTP port object (used to listen for incoming requests).
sethandlerloglevel	Changes the message logging level for the given handler.
translate	Translates the format of the policy to the latest version.
validity	Checks the working policy in the ACE XML Manager for validity problems and reports them to standard output.
version	Retrieves the product version.

"Command Reference" section provides more information on the commands.

Understanding Configuration Data

Before using the CLI commands to work with policies, it's a good idea to become acquainted with how configuration settings are kept in the ACE XML Manager. A policy is the set of configuration settings that control how traffic is passed through the ACE XML Gateway. It defines the handlers, services descriptors, access rules, and other behaviors and rules relating to service traffic.

The ACE XML appliance stores a policy in two forms:

•Working policy. The working draft of the policy in the ACE XML Manager. A working policy cannot be deployed until compiled.

•Compiled policy. Compiled policies are available for error checked and converted to the runtime format, suitable for deploying to ACE XML Gateways.

Many of the commands in the CLI require you to pass as an argument the path to the filestore you want to affect with the command. Since an ACE XML Manager can administer multiple ACE XML Gateway clusters, there may be multiple filestores on the Manager.

The working and compiled policies are kept in the following location on the ACE XML Manager file system:

var/lib/reactivity/console_documents/cluster<num>/filestore

Where cluster<num> is the directory name appropriate for the cluster you want to affect with the CLI command.

Note that the directory names of clusters are named with a prefix of "cluster" followed by an arbitrary number. To correlate a cluster as it is identified in the web console to a directory name, inspect the cluster.properties file in the cluster directory. It includes a name field that indicates the web console name for the cluster to which this policy corresponds.

You can use the grep command to retrieve this name. From the /var/lib/reactivity directory, run the following command:

grep "name=" /console_documents/*/ cluster.properties

The command returns the cluster name as it appears in the policy.

In the path passed in command arguments, replace cluster<num> with the directory name appropriate for the cluster you want to affect with the CLI command.

When using CLI commands to operate on the policy, keep in mind that operations that change policy artifacts, such as renaming handlers, are applied to the working policy, that is, the filestore contents. The policy must be compiled and deployed before the changes you perform with the CLI commands can be applied to traffic that passes through the gateways managed by the ACE XML Manager.

Since the CLI commands operate on the same filesystem data as the web console, you'll need to perform the CLI commands as the same user on the appliance, which is user agateway. When running the command as root user, you should sudo as agateway to issue the command.

If the ACE XML Manager web console is open when a CLI command is invoked that modifies a policy, the changes made by the command are not immediately reflected in the console. In general, it's recommended that you use CLI commands only when the web console is not in use.

Using the Command-Line Interface

The CLI commands are available from the Bash command line on the ACE XML appliance.

---

Note For instructions on accessing the shell, see "Accessing the bash Shell" section on page 4-15.

---

From the usr/local/reactivity directory on the ACE XML appliance, issue a CLI command in the following form:

# sudo -u agateway ./scripts/cli <command> <arg1> <arg2>  

For example, to view the release version of the software, enter the following command:

# sudo -u agateway ./scripts/cli version  

For a list of available commands, enter:

# sudo -u agateway ./scripts/cli  

You can get usage information on a particular command by entering it without arguments. For example:

# sudo -u agateway ./scripts/cli sethttpport  

Command Reference

This section provides information on the commands in the ACE XML Gateway CLI. It provides sample invocations of each command and output.

version

Prints the version number and release identifier of the ACE XML Manager software, in the form:

<version number>-<release identifier>

The release identifier can help with troubleshooting; when contacting customer support, you will often be asked for the release identifier number.

Also, it can help you ensure that all Gateway instances in a cluster are consistent in terms of their release version.

Examples

# sudo -u agateway ./scripts/cli version 

  4.2-2005-04-09TOO  

getdeployed

Retrieves the identifier, author, and compile date of the active policy on a specified Gateway. The policy author is the ACE XML Manager web console user who deployed the policy. An identifier is simply a unique identifier for the policy generated internally by the ACE XML Manager.

You can use this command to ensure that all ACE XML Gateways in a cluster are using the same policy.

getdeployed <host> <port>

Syntax Description

sudo -u agateway	IP address or hostname of the ACE XML Gateway.
port	port number on which the gateway listens for Manager traffic. The default value is 8200.

Examples

# sudo -u agateway ./scripts/cli getdeployed localhost 8200

Current policy version: ee579c2426064759

Policy author: administrator

Policy compiled on: Sat May 28 19:29:21 UTC 2005 

compile

Compiles the working policy in the ACE XML Manager, tagging it with a description you specify, and places the result in the directory:

var/lib/reactivity/console_documents/cluster<num>/filestore

Where sudo -u agateway<num> is the internal identifier for the cluster filestore. For more information on what value to use, see "Understanding Configuration Data" section

This command is generally intended for testing purposes. In most cases, you would use host, which both compiles and deploys a policy.

compile <filestore> <description>

Syntax Description

cluster	The folder that contains the working policy to be compiled. For more information, see "Understanding Configuration Data" section.
description	A brief description of this version of the policy.

deploy

Compiles the current working policy in the filestore, tags it with a description, and deploys to the specified Gateway.

---

Note Note that CLI-based deployment circumvents approval requirements that may be enabled in the ACE XML Manager, which are applicable to Manager-based deployment.

---

deploy <filestore> <host> <port> <description>

Syntax Description

deploy	The folder that contains the working policy. For more information, see "Understanding Configuration Data" section.
host	The IP address or hostname of the ACE XML Gateway to which you want to deploy the compiled policy.
port	The port number on which the gateway listens for Manager traffic. This is 8200 by default.
description	A required description for the policy.

Examples

# sudo -u agateway ./scripts/cli deploy 
var/lib/reactivity/console_documents/cluster25233/filestore 10.0.101.72 8200 myPolicy 

validity

Checks the working policy for validity problems and reports them to standard output. Examples of the types of problems this command may report include:

•expired certificate

•use of noNamespace schemas in SOAP messages

•other missing or corrupted resources

validity <filestore>

Syntax Description

filestore

The folder that contains the working policy to be validated. For more information, see "Understanding Configuration Data" section.

exportppf

Exports the current working policy to a PPF file. PPF is ACE XML Gateways's Portable Policy Format. You can use a PPF file to archive a policy to backup media or to transfer a policy from one Manager to another.

As a command argument, specify the name of the file to which the policy will be written. If a file with the same name already exists, the file is overwritten. By default, the output PPF file is written to the directory in which you run the command. From there, you can move it to another machine using filestore (secure copy) or the ftp client available on ACE XML Gateway systems.

By default, this command generates an uncompressed PPF policy file. This format is acceptable when submitting a policy for a support request, however, it cannot be directly imported into the Manager without additional processing, since the Manager expects a compressed format file.

To create a compressed format file that can be imported into the Manager, use the gz flag in the command invocation.

exportppf <filestore> <outputfile> gz

Syntax Description

filestore	The folder that contains the working policy to be exported. For more information, see "Understanding Configuration Data" section.
scp	The path and name of the file to which the policy should be written. If this file exists, it is overwritten.
filestore	Command flag that, if present, causes the output PPF to be compressed in a gzip archive. It can be imported into the Manager only if compressed in this format.

example

To generate uncompressed output:

# sudo -u agateway ./scripts/cli exportppf 
/var/lib/reactivity/console_documents/cluster25325/filestore outputfile.ppf  

For compressed output suitable for importing into the Manager:

$ sudo -u agateway ./cli exportppf 
/var/lib/reactivity/console_documents/cluster25325/filestore outputfile.gz gz 

crl_status

Reports the CRL status of the ACE XML Gateway. The CRL, or certificate revocation list, shows the revoked certificates known to the gateway.

crl_status <host> <port>

Syntax Description

outputfile	The IP address or host name of the ACE XML Gateway for which you want to view a report.
gz	The port on which the gateway listens for Manager traffic, typically host.

Examples

# sudo -u agateway ./scripts/cli crl_status 10.0.101.73 8200

<crlstatus><crl><certid>...</certid><server>10.0.101.73</server><status>Fri Jun 24 
14:59:22 UTC 2005...</status></crl></crlstatus> 

translate

When updates occur to the ACE XML Gateway product, it's possible that changes are introduced to the filestore XML format. Normally, such changes are handled transparently, as a result of the product upgrade process and by importing PPF files.

This command lets you perform the operation explicitly, translating the XML format of the working policy to the latest version. It is intended primarily for use by the product updater.

translate <filestore>

Syntax Description

port	The folder that contains the working policy to be translated. For more information, see "Understanding Configuration Data" section.

Examples

# sudo -u agateway ./scripts/translate console_documents_filestore 

replacecert

Replaces a certificate of a given filestore with another certificate. The certificate should be uploaded to the file system of the ACE XML Manager on which you are working before running this command.

replacecert <filestore> <certResourceName> <certificate>

Syntax Description

8200	The folder that contains the working policy targeted by the command. For more information, see "Understanding Configuration Data" section.
sudo -u agateway	The symbolic name of the certificate resource that you want to replace.
filestore	The certificate file you want to use to replace the current certificate.

replacepkcs12key

Replaces the named key using a PKCS12 file. The PKCS12 file should be uploaded to the file system of the ACE XML Manager on which you are working before running this command.

replacepkcs12key <filestore> <keyName> <pkcs12File> <password>

Syntax Description

sudo -u agateway	The folder that contains the working policy targeted by the command. For more information, see "Understanding Configuration Data" section.
filestore	The name of the key that you want to replace.
certResourceName	The PKCS12 file with the key that you want to use to replace the current key.
certificate	The string used to encrypt the key.

replacekeyandcert

Replaces the named key using separate key and certificate files.

replacekeyandcert <filestore> <keyName> <keyFile> <password>

Syntax Description

filestore	The folder that contains the working policy targeted by the command. For more information, see "Understanding Configuration Data" section.
keyName	The name of the key that you want to replace.
pkcs12File	The new key file you want to use.
password	The new certificate that you want to use.
filestore	The string used to encrypt the key.

renamecert

Renames the specified certificate.

renamecert <filestore> <oldCertName> <newCertName>

Syntax Description

keyName	The folder that contains the working policy to be targeted by the command. For more information, see "Understanding Configuration Data" section.
keyFile	The name of the certificate that you want to rename.
certFile	The new name for the certificate.

renamehandler

Renames a specified handler. If more than one handler with the same name exists in the filestore, an error message appears that indicates the number of occurrences of the named handler.

renamehandler <filestore> <oldHandlerName> <newHandlerName>

Syntax Description

password	The folder that contains the working policy targeted by the command. For more information, see "Understanding Configuration Data" section.
filestore	The name of the handler that you want to rename.
oldCertName	The new name for the handler.

Examples

# sudo -u agateway ./scripts/cli renamehandler 
var/lib/reactivity/console_documents/cluster25233/filestore oldname newname  

setserverhostname

Changes the hostname for a given back-end HTTP server. This value is used to address outgoing request traffic to the server.

setserverhostname <filestore> <serverName> <newHost>

Syntax Description

newCertName	The folder that contains the working policy targeted by the command. For more information, see "Understanding Configuration Data" section.
filestore	The name of the HTTP that you want to modify. This is the symbolic name of the server used in the ACE XML Manager.
oldHandlerName	The new host name for the HTTP server.

Examples

# sudo -u agateway ./scripts/cli setserverhostname  
 var/lib/reactivity/console_documents/cluster25233/filestore erpserver server2 

   Found one HTTPServer named: 'erpserver'

   Server hostname set

setserverport

Changes the port for the given back-end HTTP server. This value is used to address outgoing request traffic to the server.

setserverport <filestore> <serverName> <newPort>

Syntax Description

newHandlerName	The folder that contains the working policy targeted by the command. For more information, see "Understanding Configuration Data" section.
filestore	The name of the HTTP that you want to modify. This is the logical name of the server, as it is known in the policy.
serverName	The new HTTP port number to which to address traffic to the server.

Examples

# sudo -u agateway ./scripts/cli setserverport      
var/lib/reactivity/console_documents/cluster25233/filestore erpserver 81 

Found one HTTPServer named: 'erpserver'

Server port set

sethttpport

Changes the HTTP port number for a port object. A port object defines the port number, along with other listening port attributes, on which handlers listen for incoming traffic.

sethttpport <filestore> <portName> <newPortNumber>

Syntax Description

newHost	The folder that contains the working policy targeted by the command. For more information, see "Understanding Configuration Data" section.
filestore	The logical name of the port object, as it is known in the policy.
serverName	The new port number on which the named port object listens for incoming traffic.

Examples

# sudo -u agateway ./scripts/cli sethttpport    
var/lib/reactivity/console_documents/cluster25233/filestore myHandlerPort 8181 

   Found one HTTPPort named: 'myHandlerPort'

   Port set

sethttphostname

The newPort command lets you change the hostname on which the port object listens. (Figure 13-1 shows the equivalent setting in the ACE XML Manager web console.)

Figure 13-1 Hostname port attribute

sethttphostname <filestore> <portName> <newHostname>

Syntax Description

filestore	The folder that contains the working policy targeted by the command. For more information, see "Understanding Configuration Data" section.
portName	The logical name of the port object, as it is known in the policy.
newPortNumber	The new hostname on which the port object listens for incoming traffic.

Examples

# sudo -u agateway ./scripts/cli sethttphostname 
var/lib/reactivity/console_documents/cluster25233/filestore myPort docs.example.com 

Found one HTTPPort named: 'myHandlerPort'

Hostname set

sethandlerloglevel

Changes the message logging level for the given handler.

sethandlerloglevel <filestore> <handlerName> <level>

Syntax Description

sethttphostname	The folder that contains the working policy targeted by the command. For more information, see "Understanding Configuration Data" section.
filestore	The logical name of the handler object, as it is known in the policy.
portName	The new log level, with the following options: •newHostName for logging of inbound and outbound message bodies. •filestore for logging of outbound message bodies only. •handlerName log statistics only, no message content.