Sun Java System Web Server 6.1 SP12 Administrator's Guide

Appendix A Command Line Utilities

This appendix contains instructions for working with the HttpServerAdmin command line utility.

HttpServerAdmin (Virtual Server Administration)

HttpServerAdmin is a command line utility that performs the same administrative functions as the virtual server user interface in the Server Manager and the Class Manager. If you prefer to set up your virtual servers using the command line interface, use HttpServerAdmin.


Note –

To use the HttpServerAdmin command line utility, you must have superuser privileges on the system.


The HttpServerAdmin command line utility is located in the server_root/bin/https/httpadmin/bin directory.

Before you can run HttpServerAdmin, you need to set the environment variable IWS_SERVER_HOME to the server root directory in your environment.

For example, on UNIX/Linux systems:

setenv IWS_SERVER_HOME /usr/sun/servers

To set the environment variable on Windows systems, perform the following steps.

ProcedureOn Window systems

  1. On the Control Panel, choose System.

  2. Click the Environment tab.

  3. Type IWS_SERVER_HOME in the Variable field and the path to your server root in the Value field.

  4. Click Set.

  5. Click OK.


    Note –

    In order to perform all commands, you need to have write permissions to the file server.xml where the virtual server information is stored.


HttpServerAdmin Syntax

The HttpServerAdmin syntax is as follows:

HttpServerAdmin command_name command_options -d server_root -sinst http_instance

You can get an online explanation of the command parameters by typing the following command:

./HttpServerAdmin -h

There are four possible values for the command_name parameter:

Each command has its own set of command options. For more information, see the sections in this chapter that describe each command.

Regardless of the value of the command parameter, the parameters shown in HttpServerAdmin Syntax can apply to all uses of the HttpServerAdmin command.

Table A–1 HttpServerAdmin Parameters

Parameter  

Value  

-d server_root

(required). This parameter designates the path to the server root (the location where the server is installed). 

-sinst http_instance

(required). This parameter designates which instance HttpServerAdmin affects.

control Command

Use the control command to start, stop, and disable classes and virtual servers. If you do not specify a virtual server, the command starts, stops or disables every virtual server in the class.

Options

Use the options shown in Options with the control command to control classes and virtual servers.

Table A–2 Control command options

Options  

Value  

-start 

Starts the specified virtual server, or all virtual servers in the class if no virtual server is specified. 

-stop 

Stops the specified virtual server, or all virtual servers in the class if no virtual server is specified. 

-disable 

Disables the specified virtual server, or all virtual servers in the class if no virtual server is specified. 

Syntax

HttpServerAdmin control -cl classname, -control_option [-id virtual_server] -d 
server_root -sinst http_instance

Parameters

Use these parameters with the command options to control virtual servers

Table A–3 Control command parameters

Parameters  

Value  

-cl classname

Designates the virtual server class 

-id virtual_server

(optional) Designates the virtual server ID you are controlling. 

Examples

HttpServerAdmin control -cl myclass -start -id myvirtualserver -d 
/usr/sun/servers -sinst https-sun.com

HttpServerAdmin control -cl myclass -stop -id myvirtualserver -d 
/usr/sun/servers -sinst https-sun.com

HttpServerAdmin control -cl myclass -disable -id myvirtualserver -d 
/usr/sun/servers -sinst https-sun.com

create Command

Use the create command to create classes of virtual servers, virtual servers, and listen sockets.

Options

Use the options shown in Options with the create command to create classes, listen sockets, virtual servers, and resources.

Table A–4 Create command options

Option  

Value  

-c 

Creates a virtual server class. 

-l 

Creates a listen socket. 

-v 

Creates a virtual server. 

-r 

Creates a resource. 

Each of these options in turn has its own parameters, which are shown in the following sections.

Create Virtual Server Class

Use this option of the create command to create a virtual server class.

Syntax

HttpServerAdmin create -c -cl classname -docroot document_root [-obj 
obj.conf_file] [-acptlang accept_language] -d server_root -sinst http_instance

Parameters

Use the parameters shown in Parameters with the create -c command option to create classes.

Table A–5 Create virtual server class parameter

Parameter  

Value  

-cl classname

The name of the class you want to create. 

-docroot document_root

The document root for the class. This has to be an absolute path. 

-obj obj.conf_file

(optional) The obj.conf file for the class. If you do not specify this parameter, the server creates the obj.conf file as classname.obj.conf. If you want a different name for the class’ obj.conf file, specify it here.

-acptlang accept_language

(optional) If you do not specify this parameter, acptlang will be off by default. 

Example

HttpServerAdmin create -c -cl myclass1 -docroot /docs -d 
/export/sun/servers -sinst https-sun.com

Create Listen Socket

Use this option of the create command to create a listen socket.

Syntax

HttpServerAdmin create -l -ip ip_address -port port_number -sname 
server_name -id default_virtual_server [-sec security] 
[-acct number_of_accept_threads] -d server_root -sinst http_instance

Parameters

Use the parameters shown in Parameters with the create -l command option to create listen sockets.

Table A–6 Create listen socket parameters

Parameter  

Value  

-ip ip_address

The IP address for the listen socket. 

-port port_number

The port number for the listen socket. 

-sname server_name

The server name to associate with the listen socket. 

-id default_virtual_server

The ID of the default virtual server. This virtual server must exist before you can use it to create a listen socket. 

-acct number_of_accept_threads

(optional) The number of accept threads for the listen socket. 

-sec on

(optional) If specified, use on to enable security for the listen socket. If not specified, security is not enabled. 

Example

HttpServerAdmin create -l -id ls3 -ip 0.0.0.0 -port 1333 -sname 
austen -defaultvs vs2 -sec on -acct 4 -d /export/carey/server6 
-sinst https-austen.com

Create Virtual Server

Use this option of the create command to create a virtual server.

Please note that if you do not include values for some of the optional parameters, default values are provided. You can always change the default values after the virtual server is created.

Syntax

HttpServerAdmin create -v -id virtual_server -cl classname 
-urlh urlhosts [-state state][-docroot document_root] [-mime mime_types_file]
[-aclid acl_ID] -d server_root -sinst http_instance

Parameters

Use the parameters shown in Parameters with the create -v command option to create virtual servers.

Table A–7 Create listen socket parameters

Parameter  

Value  

-id virtual_server

The ID of the virtual server you are creating. 

-cl classname

The class of which the virtual server will be a member. 

-urlh URL_hosts

The URL hosts for the virtual server. You can specify more than one URL host, separated by a comma. 

-state state

(optional) Valid values are on, off, and disable. 

-docroot document_root

(optional) If you want to specify a document root for a virtual server, use this parameter. You must use an absolute path name. 

-mime mime_types_file

(optional) The name of the MIME types file for the virtual server. 

-aclid acl_ID

(optional) The ACL file ID <ACLID> used in the server.xml file

Examples

HttpServerAdmin create -v -id vs3 -cl class1 -urlh annh -d 
/export/sun/server6 -sinst https-sun.com

HttpServerAdmin create -v -id vs4 -cl class1 -urlh annh,annh2 
-state off -mime mime.types -d /export/sun/server6 -sinst 
https-sun.com

Create JDBC Connection Pool

Use the create -r command to create a new JDBC connection pool using the Command Line Interface.

Syntax

HttpServerAdmin -create -r -jdbcconnectionpool -poolname jdbcpoolname -classname classname [-steadypoolsize steadypoolsize] [-maxpoolsize maxpoolsize] [-poolresizequantity poolresizequantity] [-idletimeout idletimeout] [-maxwaittime maxwaittime] [-connectionvalidation true/false] [-connectionvalidationmethod connectionvalidationmethod] [-validationtablename validationtablename] [-failall true/false] [-desc description] [[-property propertyname=value],...]

Options

The following table summarizes all the options that you need to create connection pools with the create -r command option.

Table A–8 Create connection pool parameters

Parameter  

Value  

poolname jdbcpoolname

The pool name for the JDBC connection pool. 

classname classname

The vendor-specific classname that implements the data source. 

steadypoolsize steadypoolsize

The minimum number of connections that must be maintained in the pool 

maxpoolsize maxpoolsize

The maximum number of connections allowed in the pool. 

poolresizequantity poolresizequantity

The size of the batch by which the pool is resized when the steadypoolsize value is approached.

idletimeout idletimeout

The maximum time in seconds that a connection can remain idle in the pool. 

maxwaittime maxwaittime

The amount of time the caller will wait before getting a connection timeout. 

connectionvalidation true/false

Specifies whether connections will be validated before they are passed to the application. 

connectionvalidationmethod connectionvalidationmethod

The methods that can employ to validate database connections. Legal values are auto-commit, meta-data, and table.

validationtablename validationtablename

The name of the table if connectionvalidationmethod is set to table. 

failall true/false

Specifies whether to fail all connections in the pool and re-establish them if a single connection is determined to have failed. 

desc description

The description of the pool. 

property propertyname=value

The name-value pairs that specify standard and proprietary JDBC connection pool properties 

Example

HttpServerAdmin create -r -jdbcconnectionpool -poolname testpool 
-classname "oracle.jdbc.pool.OracleDataSource" -property 
"URL=jdbc:oracle:thin:@dbhost:1521:ORCL,user=scott,password=tige
r" -d /opt/Sun/S1WS6.1 -sinst testinstance

Create JDBC Resource

Use the create -r command to create a new JDBC resource using the Command Line Interface.

Syntax

HttpServerAdmin -create -r -jdbc -jndiname jndiname -poolname poolname [-desc description] [-enabled true/false]

Options

The following table summarizes all the options that you need to create a new JDBC resource with the create -r command option.

Table A–9 Create JDBC resource parameters

Parameter  

Value  

jndiname jndiname

The JNDI name of the resource. 

poolname poolname

The pool name for the JDBC connection pool. 

desc description

The description of the pool. 

enabled true/false

Specifies whether the resource is enabled or disabled. 

If a JDBC resource is disabled, no application component can connect to it, but its configuration remains in the server instance. 

Example

HttpServerAdmin create -r -jdbc -jndiname "jdbc/testjdbcresource" 
-poolname testpool -d /opt/Sun/S1WS6.1 -sinst testinstance

Create Custom Resource

Use the create -r command to create a new custom resource using the Command Line Interface.

Syntax

HttpServerAdmin -create -r -custom -jndiname jndiname -resourcetype resourcetype -factoryclass factoryclassname [-enabled true/false] [-desc description] [[-property propertyname=value],...]

Options

The following table summarizes all the options that you need to create a new JDBC resource with the create -r command option.

Table A–10 Create custom resource parameters

Parameter  

Value  

jndiname jndiname

The JNDI name of the resource. 

resourcetype resourcetype

The resource type. 

factoryclassname factoryclassname 

The classname of the object factory. 

enabled true/false

Specifies whether the resource is enabled or disabled. 

desc description

The description of the pool. 

property propertyname=value

The name-value pairs that specify the properties of the custom resource. 

Example

HttpServerAdmin create -r -custom -jndiname "testcustomresource" 
-resourcetype "java.lang.String" -factoryclass 
"com.mycom.test.StringFactory" -d /opt/Sun/S1WS6.1 -sinst 
testinstance

Create External JNDI Resource

Use the create -r command to create a new external JNDI resource using the Command Line Interface.

Syntax

HttpServerAdmin -create -r -external -jndiname jndiname -jndilookupname jndilookupname -restype restype -factoryclass factoryclass [-enabled true/false] [-desc description] [[-property propertyname=value],...]

Options

The following table summarizes all the options that you need to create a new external JNDI resource with the create -r command option.

Table A–11 Create external JNDI resource parameters

Parameter  

Value  

jndiname jndiname

The JNDI name of the resource. 

jndilookupname jndilookupname

The JNDI lookup name for the resource. 

restype restype

The resource type. 

factoryclass factoryclass 

The classname of the object factory. 

enabled true/false

Specifies whether the resource is enabled or disabled. 

desc description

The description of the pool. 

property propertyname=value

The name-value pairs that specify the properties of the custom resource. 

Example

HttpServerAdmin create -r -external -jndiname 
"testexternalresource" -jndilookupname "rmiconverter" -restype 
"samples.rmi.simple.ejb.ConverterHome" -factoryclass 
"com.sun.jndi.cosnaming.CNCtxFactory" -property 
"java.naming.provider.url=iiop://localhost:3700" -d 
/opt/Sun/S1WS6.1 -sinst testinstance

Create Mail Resource

Use the create -r command to create a new mail resource using the Command Line Interface.

Syntax

HttpServerAdmin -create -r -mail -jndiname jndiname -host host -user user -from from [-storeprotocol storeprotocol] [-storeprotocolclass storeprotocolclass] [-transportprotocol transportprotocol] [-transportprotocolclass transportprotocolclass] [-enabled true/false] [-desc description] [[-property propertyname=value]...]

Options

The following table summarizes all the options that you need to create a new mail resource with the create -r command option.

Table A–12 Create mail resource parameters

Parameter  

Value  

jndiname jndiname

The JNDI name of the resource. 

host host

The mail server host name. 

user user

The mail server user name. 

from from

The e-mail address the mail server uses to indicate the message sender. 

storeprotocol storeprotocol

Specifies the storage protocol service, which connects to a mail server, retrieves messages, and saves messages in folder(s). Example values are imap and pop3.

storeprotocolclass storeprotocolclass

Specifies the service provider implementation class for storage. 

You can find this class at: 

transportprotocol transportprotocol

Specifies the transport protocol service, which sends messages. 

transportprotocolclass transportprotocolclass

Specifies the service provider implementation class for transport. 

You can find this class at: 

enabled true/false

Determines whether this resource is enabled at runtime. Legal values are on, off, yes, no, 1, 0, true, false.

desc description

A description of the resource. 

property propertyname=value

The name-value pairs that specify the properties of the custom resource. 

Example

HttpServerAdmin create -r -mail -jndiname "localmail" -host 
localhost -user mailid -from mailid@mailhost -d /opt/Sun/S1WS6.1 
-sinst testinstance

delete Command

Use the delete command to delete classes of virtual servers, virtual servers, and listen sockets.

Options

Use the options shown in Options with the delete command to delete classes.

Table A–13 Delete command options

Option  

Value  

-c 

Deletes the specified virtual server class. 

-l 

Deletes the specified listen socket IDs 

-v 

Deletes the specified virtual servers. 

-r 

Deletes the specified resource. 

Delete Class

Use this option of the delete command to delete a virtual server class.

Syntax

HttpServerAdmin delete -c -cl classname -d server_root -sinst http_instance

Parameters

Use the parameters shown in Options with the delete command to delete classes.

Table A–14 Delete class parameters

parameter  

Value  

-c l class

The class name you want to delete. 

Example


HttpServerAdmin delete -c -cl class1 -d /export/sun/server6 -sinst https-sun.com

               

Delete Listen Socket

Use this option of the delete command to delete a listen socket.

Syntax

HttpServerAdmin delete -l -id listen_socket -d server_root -sinst http_instance

Parameters

Use the parameters shown in Options with the delete command to delete classes.

Table A–15 Delete class parameters

parameter  

Value  

-id listen_socket

The ID of the listen socket you want to delete. 

Example


HttpServerAdmin delete -l -id ls3 -d /export/sun/server6 -sinst https-sun.com

               

Delete Virtual Server

Use this option of the delete command to delete a virtual server.

Syntax

HttpServerAdmin delete -v -id virtual_server -cl classname -d server_root -sinst http_instance

Parameters

Use the parameters shown in Options with the delete command to delete a virtual server.

Table A–16 Delete virtual server parameters

parameter  

Value  

-id virtual_server

The virtual server ID you want to delete 

-cl class

The class the virtual server belongs to. 

Example

HttpServerAdmin delete -v -id vs3 -cl class1 -d 
/export/sun/server6 -sinst https-sun.com

Delete JDBC Connection Pool

Use this option of the delete command to delete a connection pool.

Syntax

HttpServerAdmin delete -r jdbcconnectionpoolname

Parameters

Use the parameters shown in Options with the delete command to delete a connection pool.

Table A–17 Delete connection pool parameters

parameter  

Value  

connectionpoolname

The name of the connection pool you want to delete 

Example


HttpServerAdmin delete -r connpool

               

Delete JNDI Resource

Use this option of the delete command to delete a JNDI resource.

Syntax

HttpServerAdmin delete -r jndiname

Parameters

Use the parameters shown in Options with the delete command to delete a JNDI resource.

Table A–18 Delete JNDI resource parameters

parameter  

Value  

jndiname

The JNDI name of the resource you want to delete 

Example


HttpServerAdmin delete -r testresource

               

list Command

Use the list command to list classes of virtual servers, virtual servers, listen sockets, and resources.

Syntax

HttpServerAdmin list -command_option -d server_root -sinst http_instance

Options

Table A–19 List command options

Option  

Value  

-c 

Lists all virtual server classes. 

-l 

Lists all listen sockets. 

-v 

Lists all virtual servers. 

-r 

Lists the specified resources 

Example


HttpServerAdmin list -c -d /export/sun/server6 -sinst https-sun.com

HttpServerAdmin list -l -d /export/sun/server6 -sinst https-sun.com

            

The list of information appears in your command window.