Chapter 12: Using jagtool and jagant

Working with jagtool

Before using jagtool, make sure that:

The JAGUAR environment variable is set.
UNIX $JAGUAR/bin is added to your path.
Windows %JAGUAR%\bin is added to your path.

Use the following scripts to run jagtool:

UNIX $JAGUAR/bin/jagtool

Windows %JAGUAR%\bin\jagtool.bat

jagtool syntax

The syntax for jagtool is:

jagtool [connect-args | local-args] [log-arg] [command]

Where:

connect-args is a list of arguments required to run in connected mode.
local-args is a list of arguments required to run in local mode.
log-arg is an optional argument to specify a file name to record jagtool output. If you do not specify a file name, output goes to the standard output device. Specify a file name with the -logfile filename argument or -l filename.
command is a jagtool command described in “jagtool commands”.

Local versus connected mode

You can run jagtool in two modes. In connected.mode, jagtool connects to a server which can be running locally or on a remote machine. In local mode, jagtool does not require a connection to a server, but must be run on a machine with file system access to the EAServer installation.

Using connected mode

Connected mode is jagtool’s default mode of operation. All commands can run in connected mode. When using connected mode, specify the arguments listed in Table 12-1.

**Table 12-1: Jagtool connection arguments**
Parameter	To specify
`-h hostname` or `-host hostname`	Server host name. If not specified, the default is the value of the JAGUAR_HOST_NAME environment variable.
`-n port` or `-port port`	Server IIOP port number. If not specified, the default is 9000.
`-u name` or `-user name`	User name. If not specified, the default is “jagadmin”.
`-p password` or `-password password`	Password. If not specified, the default is “” (no password).

For example, to connect to the server running on eclipse at port 9005, using account jagadmin with password secret enter:

jagtool -h eclipse -n 9005 -p secret

You can omit the -u flag because jagadmin is the default user name.

Unless otherwise specified in the command reference page, all commands can run in connected mode.

Using local mode

Local mode allows you to configure an EAServer installation without requiring a connection to a server. Local mode is helpful in situations where it is not convenient to start a server, for example, when using jagtool to configure new installations. Not all commands can run in local mode. To see whether a command supports local mode, check the syntax listing for the command in this chapter or check the help output for the command.

To run in local mode, specify the arguments in Table 12-2.

**Table 12-2: Jagtool local-mode arguments**
Parameter	To specify
`-local`	Specifies whether to run in local mode, without a connection to the server. If not specified, jagtool requires a connection to a running server.
`-server servername`	Specifies the name of the server to use when running in local mode. Specify the name of the server that you would connect to if running in connected mode. If you do not specify a server name, the default is Jaguar.

Local mode also requires the following:

You must be logged in to the operating system as a user with read and write privileges on the EAServer installation directory and all subdirectories.
You must set the JAGUAR environment variable set to specify the local installation directory.

When running jagtool or jagant locally, the user name and password arguments are optional. If supplied, these arguments are ignored.

Not all commands can run in local mode. The reference page for each command indicates whether the command supports local mode.

Entity identifiers

Many jagtool commands take one or more entity identifiers as arguments. An entity identifier is a string of the form EntityType:EntityName that uniquely identifies an entity in the repository.

Table 12-3 provides examples of entity identifiers for each entity type.

**Table 12-3: Example entity identifiers**
Entity Identifier	Specifies
`Agent:agent1`	Agent named agent1.
`Application:estore`	Application named estore.
`ApplicationClient:estore/PetStoreClient`	Application client PetstoreClient in application estore.
`Cluster:TheBigCluster`	The cluster named TheBigCluster.
`Component:SVU/SVULogin`	Component named SVULogin that is installed in the SVU package. The package name is included because EAServer components always reside in packages.
`ConnCache:JavaCache`	Connection cache named JavaCache.
`Connector:BlackBoxLocalTx`	J2EE connector named BlackBoxLocalTx.
`DatabaseType:Sybase_ASA`	Database type definition named Sybase_ASA.
`EntityCollection:MyEntityCollection`	The entity collection named “MyEntityCollection.”
`Filter:WebTier/MyFilter`	The servlet filter MyFilter installed in the Web application WebTier.
`InstancePool:MyPool`	The named instance pool MyPool.
`Listener:Jaguar/iiops1`	The network listener iiops1 installed in the server named Jaguar. When specifying a listener name, use the server name and the listener name as displayed in EAServer Manager.
`ManagedConnectionFactory:BlackBoxLocalTx/EASDemo`	The managed connection factory EASDemo in the J2EE connector named BlackBoxLocalTx.
`Method:SVU/SVULogin/isLogin`	The isLogin method of component SVULogin in package SVU.
`Package:SVU`	The package named SVU.
`Role:MyRole`	The role named MyRole.
`Security:sample1`	The security entity named “sample1.”
`Server:Jaguar`	The server named Jaguar.
`Service:MyPack/MyComp`	The service component MyComp, installed in package MyPack. Use this syntax to install or remove service components from a server.
`Servlet:StandAloneServlet`	The servlet named StandaloneServlet. This syntax is valid only for servlets that are not installed in a Web application.
`Servlet:MyWebApp/MyServlet`	The servlet named MyServlet in Web application named MyWebApp. You must use this syntax for servlets that are installed in a Web application.
`WebApplication:WebTier`	The Web application named Web tier.

Not all jagtool commands support every type of entity in the repository. For example, the refresh command is not supported for the Listener entity type.

When a command specifies an invalid entity type, an appropriate error message is displayed.