8.4 Configuring Routes

When you create a configuration, a virtual server is automatically created with the listener that you specified while creating the configuration. For the automatically created virtual server, as well as for any virtual server that you add subsequently in the configuration, a default route is created. The default route rule specifies that all requests to the virtual server should be routed to the origin-server pool that you specified while creating the virtual server. The default route of a virtual server cannot be deleted, but you can change its properties.

You can create additional routes for the virtual server, to route requests that satisfy specified conditions to specific origin-server pools. For example, in a banking software solution, if customer transactions for loans and deposits are processed by separate applications, you can host each of those applications in a separate origin-server pool behind an Oracle Traffic Director instance. To route customer requests to the appropriate origin-server pool depending on whether the request pertains to the loans or deposits applications, you can set up two routes as follows:

Route 1: If the request URI starts with /loan, send the request to the origin-server pool that hosts the loans application.
Route 2: If the request URI starts with /deposit, send the request to the origin-server pool that hosts the deposits application.

When a virtual server that is configured with multiple routes receives a request, it checks the request URI against each of the available routes. The routes are checked in the order in which they were created.

If the request satisfies the condition in a route, Oracle Traffic Director sends the request to the origin-server pool specified for that route.
If the request does not match the condition in any of the defined routes, Oracle Traffic Director sends the request to the origin-server pool specified in the default route.

WebSocket upgrade is enabled by default. In the Administration Console, use the WebSocket Upgrade check box to enable or disable WebSocket protocol for a route. Similarly, WebSocket protocol can also be enabled or disabled using the websocket-upgrade-enabled property, which can be set using the set-route-prop CLI command. For more information, see Oracle Traffic Director Command-Line Reference.

You can configure routes in a virtual server by using either the administration console or the CLI.

Note:

When you modify a virtual server, you are, in effect, modifying a configuration. So for the new virtual-server settings to take effect in the Oracle Traffic Director instances, you should redeploy the configuration as described in Section 4.3, "Deploying a Configuration."
The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Section 2.3.1, "Accessing the Command-Line Interface."

Configuring Routes Using the Administration Console

To configure routes by using the administration console, do the following:

Log in to the administration console, as described in Section 2.3.2, "Accessing the Administration Console."
Click the Configurations button that is situated at the upper left corner of the page.

A list of the available configurations is displayed.
Select the configuration for which you want to configure routes.
In the navigation pane, expand Virtual Servers, expand the name of the virtual server for which you want to configure routes, and select Routes.

The Routes page is displayed. It lists the routes that are currently defined for the virtual server.

Creating a Route
1. Click New Route.
  
  The New Route dialog box is displayed.
  
  In the Name field, enter a name for the new route.
  
  In the Origin Server Pool field, select the origin-server pool to which requests that satisfy the specified condition should be routed.
2. Click Next.
  
  In the Condition Information pane, select a Variable/Function and an Operator from the respective drop-down lists, and provide a value in the Value field.
  
  Select the and/or operator from the drop-down list when configuring multiple expressions. Similarly, use the Not operator when you want the route to be applied only when the given expression is not true.
  
  Click Ok.
  
  To enter a condition manually, click Cancel and then click Edit Manually. In the Condition field, specify the condition under which the routing rule should be applied. For information about building condition expressions, click the help button near the Condition field or see "Using Variables, Expressions, and String Interpolation" in the Oracle Traffic Director Configuration Files Reference.
3. Click Next and then click Create Route.
  
  The route that you just created is displayed on the Routes page.
  
  In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Section 4.3, "Deploying a Configuration."
Editing a Route

To change the settings of a route, do the following:
1. Click the Name of the route.
  
  The Route Settings page is displayed.
2. Specify the parameters that you want to change.
  
  On-screen help and prompts are provided for all of the parameters.
  
  When you change the value in a field or tab out of a text field that you changed, the Save button near the upper right corner of the page is enabled.
  
  At any time, you can discard the changes by clicking the Reset button.
3. After making the required changes, click Save.
  
  A message, confirming that the updated configuration was saved, is displayed in the Console Messages pane.
  
  In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Section 4.3, "Deploying a Configuration."
Deleting a Route Rule

To delete a route rule, click the Delete button. At the confirmation prompt, click OK.

Configuring Routes Using the CLI

To create a route, run the create-route command.

Examples:
- The following command creates a route named loan-route in the virtual server soa.example.com of the configuration soa, to send requests for which the URI matches the pattern /loan to the origin-server pool loan-app.
```
tadm> create-route --config=soa --vs=soa.example.com --condition="$uri='/loan'" --origin-server-pool=loan-app loan-route
OTD-70201 Command 'create-route' ran successfully.
```
- The following command creates a route named images-route in the virtual server soa.example.com of the configuration soa, to send requests for which the URI path matches the pattern /images to the origin-server pool images-repo.
```
tadm> create-route --config=soa --vs=soa.example.com --condition="$path='/images/*'" --origin-server-pool=images-repo images-route
OTD-70201 Command 'create-route' ran successfully.
```
- The following command creates a route named subnet-route in the virtual server soa.example.com of the configuration soa, to send requests from any client in the subnet 130.35.46.* to the origin-server pool dedicated-osp.
```
tadm> create-route --config=soa --vs=soa.example.com --condition="$ip='130.35.45.*'" --origin-server-pool=dedicated-osp subnet-route
OTD-70201 Command 'create-route' ran successfully.
```
- The following command creates a route named body-route in the virtual server soa.example.com of the configuration soa, to route requests to the origin-server pool dedicated-osp if the request body contains the word alpha.
```
tadm> create-route --config=soa --vs=soa.example.com --condition="$body ='alpha'" --origin-server-pool=dedicated-osp body-route
OTD-70201 Command 'create-route' ran successfully.
```
Note that the value of the --condition option should be a regular expression. For information about building condition expressions, see "Using Variables, Expressions, and String Interpolation" in the Oracle Traffic Director Configuration Files Reference.

To view a list of the routes defined for a virtual server, run the list-routes command, as shown in the following example:

tadm> list-routes --config=soa --vs=soa.example.com
route           condition
-------------------------
loan-route       "$uri = '/loan'"
default-route   -

To view the properties of a route, run the get-route-prop command, as shown in the following example:

tadm> get-route-prop --config=soa --vs=soa.example.com --route=loan-route
keep-alive-timeout=15
sticky-cookie=JSESSIONID
condition="$uri = '/loan'"
validate-server-cert=true
always-use-keep-alive=false
origin-server-pool=origin-server-pool-1
sticky-param=jsessionid
route-header=Proxy-jroute
rewrite-headers=location,content-location
use-keep-alive=true
route=loan-route
log-headers=false
route-cookie=JROUTE
timeout=300

To change the properties of a route, run the set-route-prop command.

Examples:
- The following command changes the keep-alive timeout setting for the route named loan-route in the virtual server soa.example.com of the configuration soa to 30 seconds.
```
tadm> set-route-prop --config=soa --vs=soa.example.com --route=loan-route keep-alive-timeout=30
```
- The following command enables logging of the headers that Oracle Traffic Director sends to, and receives from, the origin servers associated with the route named default-route in the virtual server soa.example.com of the configuration soa.
```
tadm> set-route-prop --config=soa --vs=soa.example.com --route=default-route log-headers=true
```

To delete a route, run the delete-route command, as shown in the following example:

tadm> delete-route --config=soa --vs=soa.example.com loan-route
OTD-70201 Command 'delete-route' ran successfully.

To disable WebSocket support, run the set-route-prop command with the websocket-upgrade-enabled property, as shown in the following example:

tadm> set-route-prop --config=soa --vs=soa.example.com --route=default-route websocket-upgrade-enabled=false
OTD-70201 Command 'set-route-prop' ran successfully.

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For more information about the CLI commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.