This chapter describes how to configure virtual targets. A virtual target is a prerequisite when creating a domain partition or a resource group. The chapter refers to the Fusion Middleware and Oracle Traffic Director documentation sets and online help for additional information as appropriate.
This chapter includes the following sections:
A virtual target represents a target for a resource group, both at the domain level and in a domain partition. It defines the access points to resources, such as one or more host names, a URI prefix, and the Managed Servers or cluster to which the virtual target is itself targeted.
Virtual targets are similar to virtual hosts in WebLogic Server. Like virtual hosts, virtual targets provide a separate HTTP server (web container) on each target.
A virtual target isolates a resource group from the physical attributes of where the container is running.
Each resource group requires one or more virtual targets. The virtual targets you can select depends on whether the resource group is at the domain level, or associated with a domain partition:
For domain-level resource groups, you can select any existing virtual target that is not already assigned as an available target to a partition.
For resource groups in a domain partition, you must select only from the existing virtual targets available to the partition.
Consider the following guidelines for using virtual targets:
A virtual target can be used by only one partition at a time, or at the domain level. A virtual target is never shared by more than one partition, or by a partition and the domain level.
A virtual target can be used by many resource groups within a partition, or by many resource groups at the domain level.
A virtual target can be targeted to one cluster or one Managed Server.
Many virtual targets can be targeted to the same cluster or Managed Server.
If two virtual targets have the same host names, URI prefix, and port number, they must be targeted to different clusters or Managed Servers.
A virtual target contains the following:
Host names. The list of host names for which this virtual target will serve requests. The host names you specify must have DNS entries that resolve to the correct servers, or to a load balancer:
If you are not using Oracle Traffic Director (OTD) to load balance connections for a partition, specify the actual host name of the WebLogic Server cluster or Managed Server.
If you are using OTD to load balance connections for a partition, you access applications through OTD. The host names you specify for a virtual target must resolve to the location of the OTD Administration Server.
If you do not specify a host name, it is the equivalent of using a wild card for the host name to match all incoming requests.
The host name used by a client to access the resource group must exactly match one of the host names specified in the virtual target.
You can specify multiple host names for the virtual target. You might find it convenient to specify both the simple and the fully qualified host name to ensure a match.
Optional URI prefix for which this virtual target will serve requests. For example, if you enter www.example.com as the host name and MyApp as the URI prefix, this virtual target serves requests to www.example.com/MyApp, but not to www.example.com or www.example.com/foo.
To extend this example, assume that your application root is /app. The resulting URL for the application would be www.example.com/MyApp/app.
Target cluster and Managed Server from the list of the targets in the current domain. Targets must be either a single server or a single cluster.
There are two general approaches when using virtual targets: route by hostname (http://partition1.com, http://partition2.com), or by URI prefix (http://server.com/partition1, http://server.com/partition2). You might find it easier to manage your environment if you consistently use one approach, but there is no requirement that you do so.
You must specify at least one of host name, URI prefix, or port number.
Virtual targets do not determine how a request gets to a particular server. DNS or a load balancer determine how requests get to a specific server instance. The host names used in the virtual target do not control the routing, but they must be consistent with it.
Virtual targets do determine what happens to a request once it enters a server. When a request enters a server it is matched against all of the virtual targets targeted to that server. If an incoming request matches the information on any of the virtual targets, it is assumed that the request is intended for that virtual target. If both hostnames and URI prefix are specified, then both must match. If two virtual targets match, the one with the longest URI prefix match receives the request. If none match, the request is sent to the default HTTP server.
For example, assume that you have a virtual target with the host names www.example1.com, www.example2.com, and www.example3.com. The virtual target is targeted to cluster1. Requests sent to www.example1.com, www.example2.com, and www.example3.com all match that virtual target and are all sent to cluster1.
If you specify multiple virtual targets for a resource group, the virtual target matching works the same. There is no implicit load balancing among virtual targets.
For example, assume that in PartitionA you have a virtual target with the host name www.example1.com targeted to cluster1, and a second virtual target with the host name www.example2.com targeted to cluster2. Requests sent to www.example1.com match only that virtual target and are sent only to cluster1. Requests sent to www.example2.com match only that virtual target and are sent only to cluster2.
Use Oracle Traffic Director (OTD) if you require load balancing.
You can optionally specify existing channel and port (explicit or offset) information to use as a reference for a partition-specific channel for a virtual target.
A network channel is a configurable resource that defines the attributes of a network connection to WebLogic Server. A network channel in a WebLogic Server instance is a combination of the following four attributes: communication protocol, listen address, listen port, and channel name. For more information, see "Understanding Network Channels" in Administering Server Environments for Oracle WebLogic Server.
The channel must exist on the selected target and be configured using the same protocol. If you specify a value for Partition Channel, you must specify either an explicit port or a port offset.
Allowable values for an explicit port are 1-65535, with 1-1023 (well-known or system ports) requiring system (or root) process privileges. The port must not already be bound by another process.
Consider the following example:
Create a virtual target with the host name myexample.com and the URI prefix /foo.
In the Partition Channel field, specify the existing channel Channel-1 to use as a reference for creating a partition-specific channel.
Channel-1 has a listen address and listen port of 127.0.0.1:7002 and an external address and listen port of 127.0.0.1:7002.
Specify a port offset of 5. That results in 7002 +5 for the listen port.
myexample.com must resolve to 127.0.0.1.
To access this virtual target, use myexample.com:7007/foo.
If you create another virtual target that also uses Channel-1, you must use another port offset (or explicit port) or there will be a port conflict.
In all cases, specify either an explicit port value to use as-is, or an offset. Otherwise, there is no port assigned and the channel is not created and used.
You use the WLS Administration Console to create a channel. See "Configure custom network channels" in the WLS Administration Console online help.
Note:
The partition channel is ignored if you use OTD to load balance the domain partition.Note:
Do not configure a virtual target as host name: "", URI prefix: /, explicit port: 0, port offset: 0. This configuration makes the virtual target intercept all requests intended for the default HTTP server. This configuration is not allowed.The main steps for creating a virtual target are as follows:
Enter a name for this virtual target.
Optionally, enter a URI prefix for this virtual target.
Add one or more host names for the virtual target. The host names you specify must resolve to the target cluster and Managed Servers you specify, or resolve to the OTD Administration Server if you are using OTD for load balancing.
Optionally, specify partition channel and port (explicit or offset) information to use for this virtual target, as described in Using Partition Channels With Virtual Targets. The channel must exist on the selected target and be configured using the same protocol. If you specify a value for Partition Channel, you must specify either an explicit port or a port offset.
Note:
These options are ignored if you use OTD to load balance the domain partition.Select one target from the available targets. You can select a single Managed Server or a single cluster.
If you are using the WebLogic Server Administration Console, WLST, or REST to create the virtual target, additional HTTP configuration options are available for configuring the virtual web server. For more information, see "Configure HTTP for a virtual target" in Oracle WebLogic Server Administration Console Online Help.
To create a virtual target using Fusion Middleware Control, see "Create virtual targets" in the online help.
The following example:
Creates a domain partition.
Creates a virtual target.
Sets the host name and URI prefix for the virtual target.
Targets the virtual target to the Administration Server. (You would typically not select the WebLogic Administration Server unless you have a special reason to do so.)
Adds the virtual target as an available target in the partition.
Creates the resource group.
Adds the virtual target to the resource group.
Activates the changes.
Starts the partition.
Note:
If this is the first partition created in production mode, you must restart the Administration Server before you can start the partition.
# Create virtual target
edit()
startEdit()
wls:/base_domain/edit/ !> domain=getMBean('/')
wls:/base_domain/edit/ !> peppart=domain.createPartition('Pep')
wls:/base_domain/edit/ !> vt=domain.createVirtualTarget('TestVT')
wls:/base_domain/edit/ !> vt.setHostNames(jarray.array([String('localhost')],String))
wls:/base_domain/edit/ !> vt.setUriPrefix('/foo')
wls:/base_domain/edit/ !> tgt=getMBean('/Servers/AdminServer')
wls:/base_domain/edit/ !> vt.addTarget(tgt)
wls:/base_domain/edit/ !> peppart.addAvailableTarget(vt)
wls:/base_domain/edit/ !> peprg=peppart.createResourceGroup('TestRG')
wls:/base_domain/edit/ !> peprg.addTarget(vt)
wls:/base_domain/edit/ !> activate()
wls:/base_domain/edit/ !> startPartitionWait(peppart)
For an example of creating virtual targets using REST, see "Creating Partitions" in Administering Oracle WebLogic Server with RESTful Management Services.
In particular, see the section "Create a virtual target for the new partition."
If you make a change to a virtual target that is in use by a running resource group in a running partition, you may need to restart the partition to have the change take effect.
The main steps for managing a virtual target are as follows:
Select the virtual target you want to manage.
Enter a URI prefix for this virtual target or modify the existing URI prefix
Add one or more host names for the virtual target. The host names you specify must resolve to the target cluster and Managed Servers you specify, or resolve to the OTD Administration Server if you are using OTD for load balancing.
If needed, delete one or more host names for the virtual target.
Optionally, specify partition channel and port (explicit or offset) information to use for this virtual target, as described in Using Partition Channels With Virtual Targets. The channel must exist on the selected target and be configured using the same protocol. If you specify a value for Partition Channel, you must specify either an explicit port or a port offset.
Note:
These options are ignored if you use OTD to load balance the domain partition.Select one target from the available targets. You can select a single Managed Server or a single cluster. (You would typically not select the WebLogic Administration Server unless you have a special reason to do so.)
Deselect any target you do not want to use.
If you are using the WebLogic Server Administration Console, WLST, or REST to manage the virtual target, additional HTTP configuration options are available for configuring the virtual web server. See "Configure HTTP for a virtual target" in Oracle WebLogic Server Administration Console Online Help for more information.
If you made a change to a virtual target that is in use by a running resource group in a running partition, restart the partition to have the change take effect.
To manage a virtual target using Fusion Middleware Control, see "Configure virtual targets" in the online help.
You cannot delete a virtual target that is in use by a resource group in a partition. You must first remove it from the resource group.
To delete a virtual target that is in use by a partition:
Stop the partition.
Remove the virtual target from the resource group in that partition.
Remove the virtual target from the list of available targets for the partition.
If the virtual target is used by default with the partition, deselect this option.
Restart the partition.
Delete the virtual target.
To delete a virtual target using Fusion Middleware Control, see "Delete virtual targets in use by a partition" in the online help.
You cannot delete a virtual target that is in use by a resource group at the domain level. You must first remove it from the resource group.
To delete a virtual target that is in use by a resource group at the domain level:
Remove the virtual target you want to delete from the resource group.
Delete the virtual target.
To delete a virtual target see "Delete virtual targets in use by a resource group at the domain level" in the online help.
The following example modifies the existing virtual target TestVT with the URI prefix /app and sets the host name to be myhost.example.com.
myVT is an instance of the VirtualTargetMBean.
cd('/')
edit()
startEdit()
cd('VirtualTargets')
cd ('TestVT')
cmo.setUriPrefix('/app')
cmo.setHostNames(jarray.array([String("myhost.example.com")],String))
activate()
You can also use the DomainMBean to look up a virtual target by name and return the VirtualTargetMBean.
domain=getMBean('/')
vt=domain.lookupVirtualTarget('TestVT')
vt.setUriPrefix('/app')
The following example deletes the virtual target TestVT. It first removes the virtual target as an available target for the partition Pep.
cd('/')
edit()
startEdit()
domain=getMBean('/')
vt=domain.lookupVirtualTarget('TestVT')
part=domain.lookupPartition('Pep')
part.removeAvailableTarget(vt)
domain.destroyVirtualTarget(vt)
activate()
The following example:
Creates a domain partition.
Creates a virtual target.
Sets the host name and URI prefix for the virtual target.
Targets the virtual target to the Administration Server. (You would typically not select the WebLogic Administration Server unless you have a special reason to do so.)
Adds the virtual target as an available target in the partition.
Creates the resource group.
Adds the virtual target to the resource group.
Activates the changes.
Starts the partition.
Note:
If this is the first partition created in production mode, you must restart the Administration Server before you can start the partition.Removes the Administration Server as a target.
Retargets the virtual target to Cluster-0.
# Create Pep partition and ResourceGroup
edit()
startEdit()
wls:/base_domain/edit/ !> domain=getMBean('/')
wls:/base_domain/edit/ !> peppart=domain.createPartition('Pep')
wls:/base_domain/edit/ !> vt=domain.createVirtualTarget('TestVT')
wls:/base_domain/edit/ !> vt.setHostNames(jarray.array([String('localhost')],String))
wls:/base_domain/edit/ !> vt.setUriPrefix('/foo')
wls:/base_domain/edit/ !> tgt=getMBean('/Servers/AdminServer')
wls:/base_domain/edit/ !> vt.addTarget(tgt)
wls:/base_domain/edit/ !> peppart.addAvailableTarget(vt)
wls:/base_domain/edit/ !> peprg=peppart.createResourceGroup('TestRG')
wls:/base_domain/edit/ !> peprg.addTarget(vt)
wls:/base_domain/edit/ !> activate()
wls:/base_domain/edit/ !> startPartitionWait(peppart)
startEdit()
wls:/base_domain/edit/ !> vt.removeTarget(tgt)
wls:/base_domain/edit/ !> tgt=getMBean('/Clusters/Cluster-0')
wls:/base_domain/edit/ !> vt.addTarget(tgt)
wls:/base_domain/edit/ !> activate()
For an example of creating virtual targets using REST, see "Creating Partitions" in Administering Oracle WebLogic Server with RESTful Management Services.
In particular, see the section "View the default values for a new virtual target."
See the following sections for additional information:
Configuring Domain Partitions for information on creating domain partitions.
"Understanding Network Channels" in Administering Server Environments for Oracle WebLogic Server for information on network channels.