Chapter 16 Administering Internet Connectivity

This chapter provides procedures for performing internet connectivity tasks in the Oracle GlassFish Server 3.0.1 environment by using the asadmin command-line utility.

The following topics are addressed here:

• About Internet Connectivity

• Administering HTTP Network Listeners

• Administering Virtual Servers

Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help.

About Internet Connectivity

The HTTP service provides functionality for deploying web applications and for making deployed web applications accessible by Internet clients. HTTP services are provided by two kinds of related objects: listeners and virtual servers.

The following topics are addressed here:

• About HTTP Network Listeners

• About Virtual Servers

About HTTP Network Listeners

An HTTP listener, also known as a network listener, is a listen socket that has an Internet Protocol (IP) address, a port number, a server name, and a default virtual server. Each virtual server provides connections between the server and clients through one or more listeners. Each listener must have a unique combination of port number and IP address. For example, an HTTP listener can listen for a host on all configured IP addresses on a given port by specifying the IP address 0.0.0.0. Alternatively, the listener can specify a unique IP address for each listener while using the same port.

Because an HTTP listener is a combination of IP address and port number, you can have multiple HTTP listeners with the same IP address and different port numbers, or with different IP addresses and the same port number (if your host was configured to respond to these addresses). However, if an HTTP listener uses the 0.0.0.0 IP address, which listens on all IP addresses on a port, you cannot create HTTP listeners for additional IP addresses that listen on the same port for a specific IP address. For example, if an HTTP listener uses 0.0.0.0:8080 (all IP addresses on port 8080), another HTTP listener cannot use 1.2.3.4:8080. The host running the GlassFish Server typically has access to only one IP address. HTTP listeners typically use the 0.0.0.0 IP address and different port numbers, with each port number serving a different purpose. However, if the host does have access to more than one IP address, each address can serve a different purpose.

To access a web application deployed on GlassFish Server, use the URL http://localhost:8080/ (or https://localhost:8081/ for a secure application), along with the context root specified for the web application.

To access the Administration Console, use the URL https://localhost:4848/ or http://localhost:4848/asadmin/ (console default context root).

About Virtual Servers

A virtual server, sometimes called a virtual host, is an object that allows the same physical server to host multiple Internet domain names. All virtual servers hosted on the same physical server share the IP address of that physical server. A virtual server associates a domain name for a server (such as www.aaa.com) with the particular server on which GlassFish Server is running. Each virtual server must be registered with the DNS server for your network.

Do not confuse an Internet domain with the administrative domain of GlassFish Server.

For example, assume that you want to host the following domains on your physical server: www.aaa.com, www.bbb.com, and www.ccc.com. Assume that these domains are respectively associated with web modules web1, web2, and web3. This means that the following URLs are handled by your physical server:

http://www.aaa.com:8080/web1
http://www.bbb.com:8080/web2
http://www.ccc.com:8080/web3

The first URL is mapped to virtual server www.aaa.com, the second URL is mapped to virtual server www.bbb.com, and the third is mapped to virtual server www.ccc.com. For this mapping to work, www.aaa.com, www.bbb.com, and www.ccc.com must all resolve to your physical server’s IP address and each virtual server must be registered with the DNS server for your network. In addition, on a UNIX system, add these domains to your /etc/hosts file (if the setting for hosts in your /etc/nsswitch.conf file includes files).

Administering HTTP Network Listeners

By default, when GlassFish Server starts, the following HTTP listeners are started automatically:

• HTTP listeners associated with the virtual server named server:

  • The listener named http-listener-1 does not have security enabled.

  • The listener named http-listener-2 has security enabled

• An HTTP listener named admin-listener, associated with the virtual server named __asadmin. For this listener, security is not enabled.

The following table describes the GlassFish Server default ports for the listeners that use ports.

The following topics are addressed here:

• To Create an Internet Connection

• Administering HTTP Protocols

• Administering HTTP Configurations

• Administering HTTP Transports

• Administering HTTP Network Listeners

To Create an Internet Connection

Use the subcommands in this procedure to create an internet connection with the full range of listener options. A network listener is created behind the scenes. For the shortcut version of this process , see To Create an HTTP Network Listener.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Create an HTTP or HTTPS protocol by using the create-protocol(1) subcommand with the --securityenabled option.

   To use the built-in http-listener-1 HTTP protocol, or http-listener-2 HTTPS protocol, skip this step.

3. Create an HTTP configuration by using the create-http(1) subcommand.

   To use a built-in protocol, skip this step.

4. Create a transport by using the create-transport(1) subcommand.

   To use the built-in tcp transport, skip this step.

5. (Optional) Create a thread pool by using the create-threadpool(1) subcommand.

   To avoid using a thread pool, or to use the built-in http-thread-pool thread pool, skip this step.

   For additional thread pool information, see Chapter 5, Administering Thread Pools.

6. Create an HTTP listener by using the create-network-listener(1) subcommand.

   Specify a protocol and transport, optionally a thread pool.

7. To apply your changes, restart GlassFish Server.

   See To Restart a Domain.

See Also

You can also view the full syntax and options of the subcommand by typing a command such as asadmin help create-http-listener at the command line.

Administering HTTP Protocols

Each HTTP listener has an HTTP protocol, which is created either by using the create-protocol subcommand or by using the built-in protocols that are applied when you follow the instructions in To Create an HTTP Network Listener.

The following topics are addressed here:

• To Create a Protocol

• To List Protocols

• To Delete a Protocol

To Create a Protocol

Use the create-protocol subcommand in remote mode to create a protocol.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Create a protocol by using the create-protocol(1)

   Information about options and properties for the subcommand are included in this help page.

Example 16–1 Creating an HTTP Protocol

This example creates a protocol named http-1 with security enabled.

asadmin> create-protocol --securityenabled=true http-1
Command create-protocol executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-protocol at the command line.

To List Protocols

Use the list-protocols subcommand in remote mode to list the existing HTTP protocols.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. List the existing protocols by using the list-protocols(1) subcommand.

Example 16–2 Listing the Protocols

This example lists the existing protocols.

asadmin> list-protocols
admin-listener
http-1
http-listener-1
http-listener-2
Command list-protocols executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-protocols at the command line.

To Delete a Protocol

Use the delete-protocol subcommand in remote mode to remove a protocol.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Delete a protocol by using the delete-protocol(1) subcommand

Example 16–3 Deleting a Protocol

This example deletes the protocol named http-1.

asadmin> delete-protocol http-1
Command delete-protocol executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-protocol at the command line.

Administering HTTP Configurations

Each HTTP listener has an HTTP configuration, which is created either by using the create-http subcommand or by using the built-in configurations that are applied when you follow the instructions in To Create an HTTP Network Listener.

The following topics are addressed here:

• To Create an HTTP Configuration

• To Delete an HTTP Configuration

To Create an HTTP Configuration

Use the create-http subcommand in remote mode to create a set of HTTP parameters for a protocol. This set of parameters configures one or more network listeners,

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Create an HTTP configuration by using the create-http(1) subcommand.

   Information about options and properties for the subcommand are included in this help page.

Example 16–4 Creating an HTTP Configuration

This example creates an HTTP parameter set for the protocol named http-1.

asadmin> create-http --timeout-seconds 60 --default-virtual-server server http-1
Command create-http executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-http at the command line.

To Delete an HTTP Configuration

Use the delete-http subcommand in remote mode to remove HTTP parameters from a protocol.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Delete the HTTP parameters from a protocol by using the delete-http(1) subcommand.

Example 16–5 Deleting an HTTP Configuration

This example deletes the HTTP parameter set from a protocol named http-1.

asadmin> delete-http http-1
Command delete-http executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-http at the command line.

Administering HTTP Transports

Each HTTP listener has an HTTP transport, which is created either by using the create-transport subcommand or by using the built-in transports that are applied when you follow the instructions in To Create an HTTP Network Listener.

The following topics are addressed here:

• To Create a Transport

• To List Transports

• To Delete a Transport

To Create a Transport

Use the create-transport subcommand in remote mode to create a transport for a network listener,

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Create a transport by using the create-transport(1) subcommand.

   Information about options and properties for the subcommand are included in this help page.

Example 16–6 Creating a Transport

This example creates a transport named http1-trans that uses a non-default number of acceptor threads.

asadmin> create-transport --acceptorthreads 100 http1-trans
Command create-transport executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-transport at the command line.

To List Transports

Use the list-transports subcommand in remote mode to list the existing HTTP transports.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. List the existing transports by using the list-transports(1) subcommand.

Example 16–7 Listing HTTP Transports

This example lists the existing transports.

asadmin> list-transports
http1-trans
tcp
Command list-transports executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-transports at the command line.

To Delete a Transport

Use the delete-transport subcommand in remote mode to remove a transport.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Delete a transport by using the delete-transport(1) subcommand.

Example 16–8 Deleting a Transport

This example deletes he transport named http1-trans.

asadmin> delete-transport http1-trans
Command delete-transport executed successfully. 

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-transport at the command line.

Administering HTTP Network Listeners

The following topics are addressed here:

• To Create an HTTP Network Listener

• To List HTTP Network Listeners

• To Update an HTTP Network Listener

• To Delete an HTTP Network Listener

• To Configure an HTTP Listener for SSL

• To Delete SSL From an HTTP Listener

• To Assign a Default Virtual Server to an HTTP Listener

To Create an HTTP Network Listener

Use the create-http-listener subcommand or the create-network-listener subcommand in remote mode to create a listener. These subcommands provide backward compatibility and also provide a shortcut for creating network listeners that use the HTTP protocol. Behind the scenes, a network listener is created as well as its associated protocol, transport, and HTTP configuration. This method is a convenient shortcut, but it gives access to only a limited number of options. If you want to specify the full range of listener options, follow the instructions in To Create an Internet Connection.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Create an HTTP network listener by using the create-network-listener(1) subcommand or the create-http-listener(1) subcommand.

3. If needed, restart the server.

   If you edit the special HTTP network listener named admin-listener, you must restart the server for changes to take effect. See To Restart a Domain.

Example 16–9 Creating an HTTP Listener

This example creates an HTTP listener named sampleListener that uses a non-default number of acceptor threads. Security is not enabled at runtime.

asadmin> create-http-listener --listeneraddress 0.0.0.0 
--listenerport 7272 --defaultvs server --servername host1.sun.com 
--acceptorthreads 100 --securityenabled=false 
--enabled=false sampleListener
Command create-http-listener executed successfully.

Example 16–10 Creating a Network Listener

This example a network listener named sampleListener that is not enabled at runtime:

asadmin> create-network-listener --listenerport 7272 protocol http-1
--enabled=false sampleListener
Command create-network-listener executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-http-listener or asadmin help create-network-listener at the command line.

To List HTTP Network Listeners

Use the list-http-listeners subcommand or the list-network-listeners subcommand in remote mode to list the existing HTTP listeners.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. List HTTP listeners by using the list-http-listeners(1) or list-network-listeners(1) subcommand.

Example 16–11 Listing HTTP Listeners

This example lists the HTTP listeners. The same output is given if you use the list-network-listeners subcommand.

asadmin> list-http-listeners
admin-listener
http-listener-2
http-listener-1
Command list-http-listeners executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-http-listeners or asadmin help list-network-listeners at the command line.

To Update an HTTP Network Listener

1. List HTTP listeners by using the list-http-listeners(1) or list-network-listeners(1) subcommand.

2. Modify the values for the specified listener by using the set(1) subcommand.

   The listener is identified by its dotted name.

Example 16–12 Updating an HTTP Network Listener

This example changes security-enabled to false.

asadmin> set "server.network-config.protocols.protocol.
http-listener-2.security-enabled=false"server.network-config.
protocols.protocol.http-listener-2.security-enabled=false
Command set executed successfully.

To Delete an HTTP Network Listener

Use the delete-http-listener subcommand or the delete-network-listener subcommand in remote mode to delete an existing HTTP listener. This disables secure communications for the listener.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. List HTTP listeners by using the list-http-listeners(1) subcommand.

3. Delete an HTTP listener by using the delete-http-listener(1) or delete-network-listener(1) subcommand.

4. To apply your changes, restart GlassFish Server.

   See To Restart a Domain.

Example 16–13 Deleting an HTTP Listener

This example deletes the HTTP listener named sampleListener:

asadmin> delete-http-listener sampleListener
Command delete-http-listener executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-http-listener or asadmin help delete-network-listener at the command line.

To Configure an HTTP Listener for SSL

Use the create-ssl subcommand in remote mode to create and configure an SSL element in the specified listener. This enables secure communication for the listener.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Configure an HTTP listener by using the create-ssl(1) subcommand.

3. To apply your changes, restart GlassFish Server.

   See To Restart a Domain.

Example 16–14 Configuring an HTTP Listener for SSL

This example enables the HTTP listener named http-listener-1 for SSL:

asadmin> create-ssl --type http-listener --certname sampleCert http-listener-1
Command create-ssl executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-ssl at the command line.

To Delete SSL From an HTTP Listener

Use the delete-ssl subcommand in remote mode to delete the SSL element in the specified listener. This disables secure communications for the listener.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Delete SSL from an HTTP listener by using the delete-ssl(1) subcommand.

3. To apply your changes, restart GlassFish Server.

   See To Restart a Domain.

Example 16–15 Deleting SSL From an HTTP Listener

This example disables SSL for the HTTP listener named http-listener-1:

asadmin> delete-ssl --type http-listener http-listener-1
Command delete-http-listener executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-ssl at the command line.

To Assign a Default Virtual Server to an HTTP Listener

1. In the Administration Console, open the HTTP Service component under the relevant configuration.

2. Open the HTTP Listeners component under the HTTP Service component.

3. Select or create a new HTTP listener.

4. Select from the Default Virtual Server drop-down list.

   For more information, see To Assign a Default Web Module to a Virtual Server.

See Also

For details, click the Help button in the Administration Console from the HTTP Listeners page.

Administering Virtual Servers

A virtual server is a virtual web server that serves content targeted for a specific URL. Multiple virtual servers can serve content using the same or different host names, port numbers, or IP addresses. The HTTP service directs incoming web requests to different virtual servers based on the URL.

When you first install GlassFish Server, a default virtual server is created. You can assign a default virtual server to each new HTTP listener you create.

Web applications and Java EE applications containing web components (web modules) can be assigned to virtual servers during deployment. A web module can be assigned to more than one virtual server, and a virtual server can have more than one web module assigned to it. If you deploy a web application and don't specify any assigned virtual servers, the web application is assigned to all currently defined virtual servers. If you then create additional virtual servers and want to assign existing web applications to them, you must redeploy the web applications. For more information about deployment, see the Oracle GlassFish Server 3.0.1 Application Deployment Guide.

You can define virtual server properties using the asadmin set command. For example:

asadmin> set server-config.http-service.virtual-server.MyVS.property.sso-enabled="true"

Some virtual server properties can be set for a specific web application. For details, see sun-web-app in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

The following topics are addressed here:

• To Create a Virtual Server

• To List Virtual Servers

• To Update a Virtual Server

• To Delete a Virtual Server

• To Assign a Default Web Module to a Virtual Server

• To Assign a Virtual Server to an Application or Module

To Create a Virtual Server

By default, when GlassFish Server starts, the following virtual servers are started automatically:

• A virtual server named server, which hosts all user-defined web modules.

  For development, testing, and deployment of web services in a non-production environment, server is often the only virtual server required.

• A virtual server named __asadmin, which hosts all administration-related web modules (specifically, the Administration Console). This server is restricted, which means that you cannot deploy web modules to this virtual server.

In a production environment, additional virtual servers provide hosting facilities for users and customers so that each appears to have its own web server, even though there is only one physical server.

Use the create-virtual-server subcommand in remote mode to create the named virtual server.

Before You Begin

A virtual server must specify an existing HTTP listener. Because the virtual server cannot specify an HTTP listener that is already being used by another virtual server, create at least one HTTP listener before creating a new virtual server.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Create a virtual server by using the create-virtual-server(1) subcommand.

   Information about properties for this subcommand is included in this help page.

3. To apply your changes, restart GlassFish Server.

   See To Restart a Domain.

Example 16–16 Creating a Virtual Server

This example creates a virtual server named sampleServer on localhost.

asadmin> create-virtual-server sampleServer
Command create-virtual-server executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-virutal-server at the command line.

To List Virtual Servers

Use the list-virtual-servers subcommand in remote mode to list the existing virtual servers.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. List virtual servers by using the list-virtual-servers(1) subcommand.

Example 16–17 Listing Virtual Servers

This example lists the virtual servers for localhost.

asadmin> list-virtual-servers
sampleListener
admin-listener
http-listener-2
http-listener-1
Command list-http-listeners executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-virutal-servers at the command line.

To Update a Virtual Server

1. List virtual servers by using the list-virtual-servers(1) subcommand.

2. Modify the values for the specified virtual server by using the set(1) subcommand.

   The virtual server is identified by its dotted name.

To Delete a Virtual Server

Use the delete-virtual-server subcommand in remote mode to delete an existing virtual server.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. List virtual servers by using the list-virtual-servers(1) subcommand.

3. If necessary, notify users that the virtual server is being deleted.

4. Delete a virtual server by using the delete-virtual-server(1) subcommand.

5. To apply your changes, restart GlassFish Server.

   See To Restart a Domain.

Example 16–18 Deleting a Virtual Server

This example deletes the virtual server named sampleServer from localhost.

asadmin> delete-virtual-server sampleServer
Command delete-virtual-server executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-virutal-server at the command line.

To Assign a Default Web Module to a Virtual Server

A default web module can be assigned to the default virtual server and to each new virtual server. To access the default web module for a virtual server, point the browser to the URL for the virtual server, but do not supply a context root. For example:

http://myvserver:3184/

A virtual server with no default web module assigned serves HTML or JavaServer Pages (JSP) content from its document root, which is usually domain-dir/docroot. To access this HTML or JSP content, point your browser to the URL for the virtual server, do not supply a context root, but specify the target file.

For example:

http://myvserver:3184/hellothere.jsp

To Assign a Virtual Server to an Application or Module

You can assign a virtual server to a deployed application or web module.

Before You Begin

The application or module must already be deployed. For more information, see Oracle GlassFish Server 3.0.1 Application Deployment Guide.

1. In the Administration Console, open the HTTP Service component under the relevant configuration.

2. Open the Virtual Servers component under the HTTP Service component.

3. Select the virtual server to which you want to assign a default web module.

4. Select the application or web module from the Default Web Module drop-down list.

   For more information, see To Assign a Default Web Module to a Virtual Server.