C H A P T E R  7

SGD Servers, Arrays, and Load Balancing

This chapter describes how to configure, license, and monitor Sun Secure Global Desktop (SGD) servers and arrays. Some system administration features of SGD, such as the Administration Console, log filters, and installation backups are also covered.

This chapter includes the following topics:


Arrays

In SGD, an array is a collection of SGD servers that share configuration information.

Arrays have the following benefits:

Users see the same webtop and can resume applications, no matter which SGD server they log in to.

This section includes the following topics:

The Structure of an Array

An array contains the following:

A single, standalone server is considered to be the primary server in an array with no secondary servers.

SGD servers in an array might run different operating systems. However, all the array members must run the same version of SGD.

While you are evaluating SGD you are limited to an array with two members. Once you install a license key, this restriction is removed.

As the SGD servers in an array share information about user sessions and application sessions, it is important to synchronize the clocks on the SGD hosts. Use Network Time Protocol (NTP) software, or the rdate command, to ensure the clocks on all SGD hosts are synchronized.

Replicating Data Across the Array

When the primary server replicates data to the secondary servers, it replicates the following data:

Apart from the resource files, any changes to the above data are replicated immediately. The synchronization of resource files occurs once daily, and only while the servers are running. The resource files that are synchronized are the files from the /opt/tarantella/var/serverresources directory.

Only add, modify, or delete the files in these directories on the primary server.

The time and effort that it takes to synchronize an array is directly proportional to the size of the array. Resource synchronization can be scheduled to take place at a time of your choice. In the Administration Console, this is configured with the Daily Resource Synchronization Time attribute on the Performance tab for each SGD server.

Array Communication

In the array, each SGD server has a peer Domain Name System (DNS) name and one or more external DNS names. SGD servers always use peer DNS names to communicate with each other. You also use peer DNS names when specifying array members in the SGD configuration tools. External DNS names are only used by SGD Clients when connecting to SGD servers. See DNS Names more details.

Connections between the SGD servers in an array are made on Transmission Control Protocol (TCP) port 5427. Unless explicitly enabled, this connection is not encrypted. The connection between SGD servers in an array can be encrypted by using secure intra-array communication. See Securing Connections Between SGD Servers.

Each server in the array has a record of the peer DNS names of all the SGD servers in an array. A server only accepts connections on TCP port 5427 if the following occurs:

Most connections are made from the primary server to a secondary server. These connections replicate data to keep the array synchronized. However, array members must be able to communicate directly with other array members.

Adding and Removing SGD Servers From An Array

You add and remove SGD servers from an array by using the Administration Console or by using the tarantella array command.

It is best to perform all array operations on the primary SGD server in the array.

procedure icon  How to Add a Server to an Array

The server joining the array must be a standalone server. In other words, the server must be in an array on its own.

  1. Log in to the Administration Console on the primary SGD server.

  2. Go to the Secure Global Desktop Servers tab.

  3. In the Secure Global Desktop Server List, click the Add button.

    The Add a Secure Global Desktop Server screen is displayed.



    Tip - You can also use the tarantella array join command to add an SGD server to an array.



  4. Enter the peer DNS name of an SGD server in the DNS Name field.

  5. Enter the user name and password of an SGD Administrator in the User Name and Password fields.

  6. Click Add.

    The Secure Global Desktop Servers tab is displayed.

    The Secure Global Desktop Servers tab shows messages advising you to wait for the server change and synchronization processes to complete.



    Note - After making a change to the structure of an array, wait until SGD has copied the changes to all the SGD servers in the array before making any further changes. Run the tarantella status command on the primary SGD server to check the status of the array.



    If the server you add has been load balancing application servers using Advanced Load Management, you must do a warm restart, tarantella restart sgd --warm, of the new server after it has joined the array. See also How Advanced Load Management Works.

procedure icon  How to Remove a Server From an Array

To remove the primary server from an array, you must first make another server the primary server and then remove the old primary server.

When you remove a server from an array, it loses its license keys.

  1. Log in to the Administration Console on the primary SGD server.

  2. Go to the Secure Global Desktop Servers tab.

  3. In the Secure Global Desktop Server List, click the Remove button.



    Tip - You can also use the tarantella array detach command to remove an SGD server from an array.



  4. When prompted, click OK.

    The Secure Global Desktop Servers tab shows messages advising you to wait for the server change and synchronization processes to complete.



    Note - After making a change to the structure of an array, wait until SGD has copied the changes to all the SGD servers in the array before making any further changes. Run the tarantella status command on the primary SGD server to check the status of the array.



procedure icon  How to Change the Primary Server in an Array

  1. Log in to the Administration Console on the primary SGD server.

  2. Go to the Secure Global Desktop Servers tab.

  3. In the Secure Global Desktop Server List, click the Make Primary button.



    Tip - You can also use the tarantella array make_primary command to change the primary server in an array.



  4. When prompted, click OK.

    The Secure Global Desktop Servers tab shows messages advising you to wait for the server change and synchronization processes to complete.

    The previous primary server becomes a secondary server.



    Note - After making a change to the structure of an array, wait until SGD has copied the changes to all the SGD servers in the array before making any further changes. Run the tarantella status command on the primary SGD server to check the status of the array.



Configuring Arrays and Servers

The Administration Console enables you to configure arrays and SGD servers. The attributes on the Global Settings tabs are the settings that apply to the array as a whole, for example how users authenticate to SGD. Appendix A has details of all the global settings. If you click the name of an SGD server on the Secure Global Desktop Servers tab, you display the attributes that apply only to that server, for example the server’s external DNS names. Appendix B has details of all the server-specific settings.

You can also list and edit global settings or server-specific settings from the command line, using the tarantella config command.

Array Failover

Array failover is a feature where an SGD array is “repaired” automatically if the primary server in the array becomes unavailable. The primary server can become unavailable either because of network problems, or because the SGD server goes down.

In array failover, one of the secondary servers in the array is upgraded to become the new primary server for the array. The remaining secondary servers in the array are configured automatically to work with the new primary server.

SGD uses the array’s backup primaries list to determine which secondary server to upgrade to be the new primary server.

When array failover is used, the SGD array is said to be in a repaired state.

The array failover process is automatic, and starts after the primary server has been unavailable for a user-configurable time period, called the grace period. The default grace period is 10 minutes.



Note - After array failover, if the original primary server becomes available, you can use the tarantella array commands to manually recreate the original SGD array. See Adding and Removing SGD Servers From An Array for details of how to build an SGD array manually.



Array failover is disabled by default for an SGD array.

This section includes the following array failover topics:

Examples of How Array Failover Works

There are many possible array failover scenarios, where the primary server becomes unavailable for one or more servers in the SGD array. This section includes examples of how array failover works in the following scenarios:



Note - When an array splits into two or more arrays as described in this section, you must check that each array has valid license keys. If an array does not have valid license keys, users might not be able to log in to SGD and run applications. See Licensing and SGD for more details about SGD licensing.



The examples in this section assume a starting point of a four-node SGD array, as follows:

  • Primary server – boston.indigo-insurance.com

  • Secondary servers – newyork.indigo-insurance.com, detroit.indigo-insurance.com, seattle.indigo-insurance.com.

FIGURE 7-1 shows the network configuration before array failover.

FIGURE 7-1   Network Configuration Before Array Failover

Diagram Showing Network Configuration Before
Array Failover


Primary Server Goes Down

A typical sequence of events for array failover when the primary server in an SGD array goes down is as follows:

  1. The primary server, boston.indigo-insurance.com, goes down and is unavailable to any of the secondary servers in the array.

  2. If boston.indigo-insurance.com is still unavailable after the grace period has elapsed, array failover starts.

  3. Array failover identifies the first available secondary server from the array’s backup primaries list. This secondary server is upgraded to be the new primary server for the array.

  4. Each of the existing secondary servers are reconfigured automatically to work with the new primary server. The array becomes a three-node array.

  5. The boston.indigo-insurance.com SGD server becomes available again. By default, the original primary server becomes a single, standalone SGD server and does not rejoin the array.

FIGURE 7-2 shows the network configuration after array failover.

FIGURE 7-2   Network Configuration After Array Failover When the Primary Server Goes Down

Diagram Showing Network Configuration After
Array Failover When the Primary Server Goes Down


Array Splits into Multiple Arrays

A typical sequence of events for array failover when an SGD array splits into multiple arrays is as follows:

  1. Because of network problems, the primary server, boston.indigo-insurance.com, can only contact the newyork.indigo-insurance.com secondary server. The remaining secondary servers in the array, seattle.indigo-insurance.com and detroit.indigo-insurance.com, cannot be contacted.

  2. After the grace period has elapsed, if the primary server still cannot contact seattle.indigo-insurance.com and detroit.indigo-insurance.com, array failover starts.

  3. The original array remains as a four-node array, but with the seattle.indigo-insurance.com and detroit.indigo-insurance.com servers reported as uncontactable in the array. The same primary server, boston.indigo-insurance.com, is used but the original array now has only a single contactable secondary server, newyork.indigo-insurance.com.

  4. The secondary servers seattle.indigo-insurance.com and detroit.indigo-insurance.com can contact each other. These servers join to form a new two-node array. Array failover determines the primary server for this array, by selecting the first available secondary server from the backup primaries list.

  5. Network problems are fixed. By default, the two arrays continue to run independently. The original array is reset so that it now contains only two members, boston.indigo-insurance.com and newyork.indigo-insurance.com.

FIGURE 7-3 shows the network configuration after array failover.

FIGURE 7-3   Network Configuration After Array Failover When the Array Splits into Multiple Arrays

Diagram Showing Network Configuration After
Array Failover When the Array Splits into Multiple Arrays


Configuring Array Failover

Array failover is disabled by default for an SGD array. To enable array failover for an SGD array, run the following command on any SGD server in the array:


$ tarantella config edit --array-failoverenabled 1

By default, array failover starts 10 minutes after the primary server in the array becomes unavailable. This time period, called the grace period, is calculated from the default values for the Array Monitor Interval (--array-monitortime) and Array Monitor Attempts (--array-maxmonitors) global settings, as follows:

Grace period = 60 seconds x 10 = 600 seconds, or 10 minutes.

To change the grace period, you can use tarantella config edit to adjust either or both of these settings. For example, to change the grace period to 300 seconds, or 5 minutes, run the following commands on any SGD server in the array:


$ tarantella config edit --array-monitortime 50
$ tarantella config edit --array-maxmonitors 6

About the Backup Primaries List

Array failover uses the backup primaries list to select a secondary server to upgrade to be the new primary server in the array. The backup primaries list is a list of secondary servers, with the priority decreasing from top to bottom. If available, array failover upgrades the highest priority secondary server in this list to be the new primary server for the array.

The backup primaries list is stored on each SGD server in the array. Any changes made to the list are copied to each SGD server in the array.

Only SGD servers that are in the backup primaries list can be used in array failover.

If the backup primaries list is empty, all SGD servers in the array become standalone servers after array failover.



Note - When you build an SGD array, a backup primaries list is created for you automatically. If you add a secondary server to the array, an entry is added at the end of the list. If you remove a secondary server from the array, the entry for the server is removed from the list.



The backup primaries list can be viewed and edited from any SGD server in the array using the tarantella array command.

For example, to show the list of backup primaries for an SGD array, run the following command:


$ tarantella array list_backup_primaries
Backup Primaries (2)
0 - seattle.indigo-insurance.com
1 - newyork.indigo-insurance.com

In this example, the highest priority secondary server is entry 0, seattle.indigo-insurance.com. If this secondary server is available, array failover upgrades it to be the new primary server in the array.

For example, to add a new entry to the backup primaries list:


$ tarantella array add_backup_primary \ 
--secondary detroit.indigo-insurance.com \
--position first



Note - The specified secondary server must be a member of the SGD array.



To change the position of an entry in the backup primaries list:


$ tarantella array edit_backup_primary \ 
--secondary detroit.indigo-insurance.com \
--position 1

In this example, the secondary server detroit.indigo-insurance.com is moved to second place to the backup primaries list.

To delete an entry from the backup primaries list:


$ tarantella array remove_backup_primary \ 
--secondary detroit.indigo-insurance.com

Cleaning an Array

In some situations after using array failover you might want to delete all array state information for an SGD array. For example, you might want to rebuild the array starting from single, standalone SGD servers. You use the tarantella array clean command to do this.

The tarantella array clean command deletes all array state information, including information about the original array members before array failover.

You run the command on each SGD server in the array, as follows:


$ tarantella array clean

By default, the tarantella array clean command deletes all array information and configures the SGD server as a single, standalone server. Use the --contactmembers option of this command if you want the SGD server to remain in an array with other SGD servers that are contactable and that report the same array membership.



caution icon

Caution - After you run tarantella array clean on the primary server in an SGD array, the secondary servers will not be able to contact the primary server.




Load Balancing

Load balancing helps you scale up to support more users so that they receive a reliable and high-performance service without any single point of failure.

SGD supports the following load balancing mechanisms:

User Session Load Balancing

User session load balancing is concerned with choosing a SGD server to log in to. Users can log in to any SGD server in an array and access the same applications.

User session load balancing happens before the first connection is made to SGD. You can use a number of mechanisms to choose an appropriate SGD server, for example:

When load balancing user sessions, the most important factor is session persistence. A user session begins when a user logs in to an SGD server and the session is owned by that server. As the user interacts with SGD, further requests are sent over the Hypertext Transfer Protocol (HTTP) connection to the SGD server. If network connections are load‐balanced, HTTP requests might be directed to any SGD server in the array. If an HTTP request goes to an SGD server that does not own the user session, the following can occur:

To load balance user sessions successfully, HTTP requests must persist so that they always go to the correct SGD server.

In a default SGD installation, additional configuration is required to make HTTP connections persistent. SGD supports the following mechanisms:

Instructions on how to install, configure, and use the SGD Gateway are included in the Sun Secure Global Desktop 4.5 Gateway Administration Guide.

The load-balancing JSP technology page can only be used if the following conditions are met:

The load‐balancing JSP technology page can be used in the following ways:

Using The Load-Balancing JSP Technology Page to Distribute User Sessions

To use the load-balancing JSP technology page to distribute user sessions, one member of the array acts as the load distribution server. Typically this is the primary SGD server in the array. On the load distribution server, you configure the load-balancing JSP technology page with a list of SGD servers that can host user sessions. Users connect to the load distribution server and the load‐balancing JSP technology page redirects them to an SGD server in the list using a round‐robin mechanism.

Users must connect to the load distribution server using a URL that connects to the load‐balancing JSP technology page, usually this is http://server.example.com/sgd, where server.example.com is the name of an SGD server.

To use Hypertext Transfer Protocol over Secure Socket Layer (HTTPS) connections, you configure SGD as follows:

  • Use an HTTP connection to the load distribution server.

  • Configure HTTPS URLs for the SGD servers in the load-balancing JSP technology page.

procedure icon  How to Configure the Load‐Balancing JSP Technology Page to Distribute User Sessions

Select one member of the array to act as the load distribution server. The following procedure uses the primary SGD server in the array.

  1. Log in as superuser (root) on the primary SGD server in the array.

  2. Copy the load-balancing JSP technology pages to the /sgd web application directory.

    For example:


    # cd /opt/tarantella/webserver/tomcat/6.0.18_axis1.4/webapps/sgd/
    # cp -rp admin/loaddist/ swcd/
    



    Note - When you copy the files, use the -p option to preserve the file permissions.



  3. Edit the load-balancing JSP technology page.

    The load‐balancing JSP technology page is swcd.jsp.

    1. Add the external DNS names of the SGD servers to be load balanced.

      See Configuring External DNS Names for details.

      Amend the hosts = new Array section, for example:

      hosts[0] = "http://www1.example.com"
      hosts[1] = "http://www2.example.com"
      ...
      hosts[4] = "http://www5.example.com"

      If you are using secure connections, ensure the URLs begin with https://.

      Only include the primary SGD server in the list if you want the primary server to host user sessions.

    2. Set the LBHOST variable.

      Remove the first comment marks (//) as follows:

      var LBHOST = null // Not in Load Balancer/Round Robin DNS mode

    3. Save the changes.

  4. Configure the SGD entry point JSP technology page to use the load-balancing JSP technology page.

    The entry point JSP technology page is index.jsp.

    1. Change the first line to the following:

      <%@ include file="swcd/swcd.jsp" %>

    2. Save the change.

Using an External Mechanism to Distribute User Sessions

When using an external mechanism, such as a hardware load balancer or round‐robin DNS, for load balancing user sessions, the following factors are important:

  • External DNS names. The SGD servers in the array must be directly accessible using their external DNS names. If an external load balancer is acting as a firewall, a switch, or a router, it must be configured to allow access using the external DNS names. See Configuring External DNS Names.

  • Adaptive Internet Protocol (AIP) connections. AIP connections must go to the SGD server that is hosting the application session. An external load balancer must not distribute the connections to different SGD servers in the array.

  • AIP is not HTTP. If you enable SGD security services, AIP connections are encrypted using Secure Sockets Layer (SSL). If an external load balancer decrypts the SSL for an AIP request, it cannot handle the remaining contents.

  • URL rewriting. An external load balancer can be configured to rewrite URLs. The impact of a connection to SGD using a URL containing a host name that does not match the external DNS name of the SGD server is undefined.

  • Virtual hosting multiple HTTPS connections. To use HTTPS connections to an external load balancer and the SGD web server requires two SSL certificates: one for the load balancer DNS name and one for the external DNS name of the SGD server. You can only do this by using virtual hosting to create two web servers on the same host, each with a different DNS name. However, the web servers must use either different TCP ports or different Internet Protocol (IP) addresses.

To use an external mechanism to distribute user sessions, you configure the load‐balancing JSP technology page on every SGD server in the array.

If you are using a hardware load balancer, the load balancer must be configured to allow access to the SGD servers using their external DNS names. Typically the load balancer is also an SSL accelerator. With this configuration, the connection to SGD is processed as follows:

  1. Users make HTTPS connections to the load balancer DNS name.

  2. The load balancer decrypts the SSL request and forwards it as an HTTP request to the external DNS name of the selected SGD server.

  3. The load-balancing JSP technology page on the SGD server checks for the load-balancing cookie and redirects the HTTP request to the correct SGD server as needed.

Users must connect to SGD using a URL that contains the DNS name of the load balancer, for example https://loadbalancer.indigo‐insurance.com/sgd.

If SGD security services are enabled, and the external load balancer is configured to decrypt SSL connections and forward them as unencrypted connections, you must configure each SGD server in the array to accept plain text connections on the secure port. See Using External SSL Accelerators for details.

To use HTTPS connections between the load balancer and the SGD servers, ensure that the URLs in the load‐balancing JSP technology page begin with https://. Then perform either of the following configurations:

  • Configure the external load balancer to terminate the load‐balanced HTTPS connection and then regenerate the connection as an HTTPS connection to the external DNS name of the SGD server.

  • Assign an additional IP address to the SGD host and configure the host to use this address. Configure the SGD web server to listen on the additional IP address and associate the SSL certificate for the load balancer with this address. Configure the SGD web server to associate the external DNS name of the SGD server with the original IP address of the server. Configure the load balancer to use the additional IP addresses.

Using SGD in firewall traversal mode can also help to simplify the configuration needed when using an external load balancer. With firewall traversal, the HTTP and AIP connections to SGD are made over a single port, usually TCP port 443. See Using Firewall Traversal.

procedure icon  How to Configure the Load‐Balancing JSP Technology Page for an External Load Balancing Mechanism

The following procedure is an example of how to configure the load‐balancing JSP technology page on an SGD server when using an external load balancing mechanism.

All the SGD servers in the array must be configured in the same way.

  1. Log in as superuser (root) on the SGD host.

  2. Copy the load-balancing JSP technology page files to the /sgd web application directory.

    For example:


    # cd /opt/tarantella/webserver/tomcat/6.0.18_axis1.4/webapps/sgd/
    # cp -rp admin/loaddist/ swcd/
    



    Note - When you copy the files, use the -p option to preserve the file permissions.



  3. Edit the load-balancing JSP technology page.

    The load‐balancing JSP technology page is swcd.jsp.

    1. Add the external DNS names of the SGD servers to be load balanced.

      See Configuring External DNS Names for details.

      Amend the hosts = new Array section, for example:

      hosts[0] = "http://www1.example.com"
      hosts[1] = "http://www2.example.com"
      ...
      hosts[4] = "http://www5.example.com"

    2. Set the LBHOST variable.

      Remove the first comment marks (//) and enter the external DNS name of the SGD server, for example:

      var LBHOST = "http://www1.example.com" // LB mode

    3. Save the changes.

  4. Configure the SGD entry point JSP technology page to use the load-balancing JSP technology page.

    The entry point JSP technology page is index.jsp.

    1. Change the first line to the following:

      <%@ include file="swcd/swcd.jsp" %>

    2. Save the change

procedure icon  How to Configure the Load‐Balancing JSP Technology Page for Use With My Desktop

See Using My Desktop for details of the My Desktop features.

All the SGD servers in the array must be configured in the same way.

  1. Log in as superuser (root) on the SGD host.

  2. Copy the load-balancing JSP technology page files to the /sgd/mydesktop web application directory.

    For example:


    # cd /opt/tarantella/webserver/tomcat/6.0.18_axis1.4/webapps/sgd/
    # cp -rp admin/loaddist/ mydesktop/swcd/
    



    Note - When you copy the files, use the -p option to preserve the file permissions.



  3. Configure My Desktop to use the load-balancing JSP technology page.

    1. Rename the My Desktop entry point JSP technology page.

      The entry point JSP technology page is mydesktop/index.jsp.

      For example:


      # mv mydesktop/index.jsp mydesktop/mydesktop.jsp
      

    2. Create a new entry point JSP technology page for My Desktop.

      Create a new JSP technology page file, mydesktop/index.jsp, with the following content:

      <%@ include file="/mydesktop/swcd/swcd.jsp" %>

    3. Check the file permissions for the My Desktop JSP technology page files.


      # chmod root:ttaserv mydesktop/index.jsp mydesktop/mydesktop.jsp
      

  4. Edit the load-balancing JSP technology page.

    The load‐balancing JSP technology page is mydesktop/swcd/swcd.jsp.

    1. Add the external DNS names of the SGD servers to be load balanced and set the LBHOST variable.

    2. Set the TARGET variable.

      You must change the TARGET variable so that it directs users to My Desktop instead of the webtop.

      var TARGET="/sgd/mydesktop/mydesktop.jsp"

    3. Save the changes.

Additional Load‐Balancing JSP Technology Page Configuration

This section describes the additional configuration that is available for the load‐balancing JSP technology page.

Using Another Webtop

The load‐balancing JSP technology page connects users to the standard webtop. To use another webtop, for example a customized webtop, amend the following line:

var TARGET="/sgd/standard.jsp"

Localized Splash Screen

The load-balancing JSP technology page displays a splash screen in English using the images in the /sgd/swcd/ directory. To display a localized splash screen, change the default location of the splash screen images in the following lines:

// ** Location of gif files
<%
// If the gifs are located in the locale dependent resource use the Path below
String path = getContextPath(request) + "/resources/images/splash/locale=" +
getBestSupportedLocale(request) + "/";
// Default location
//String path = "swcd/";
%>

Other Variables

The following are the other variables used by the load-balancing JSP technology page:

  • SGDLDCOOKIE

    The name of the cookie used for load balancing purposes.

    The default is SGD_SWCDCOOKIE.

  • TIMEOUT

    The time in milliseconds the load-balancing JSP technology page waits for a response from the SGD web server on the selected host. If the timeout period elapses, the next host in the list is tried.

    The default is 10000 milliseconds.

  • TESTGIF

    The file the load-balancing JSP technology page attempts to get from the SGD web server on the selected host. This is used to check whether the host is available.

    The default is /sgd/resources/images/webtop/secure.gif.

Application Session Load Balancing

Application session load balancing is concerned with choosing an SGD server to manage an application session.

An application session consists of a set of data about the session, for example the user identity of the user that started the session, and a Protocol Engine process. The Protocol Engine process runs on an SGD server and performs the following tasks:

A Protocol Engine process can run on any SGD server in the array. This is not necessarily the same server that hosts the user session, which is the SGD server the user logged in to.

SGD can load balance application sessions across all the SGD servers in the array. The more servers you have, the less the load on each. In the Administration Console, you configure application session load balancing on the Global Settings -> Performance tab. You can configure SGD to use one of the following methods for selecting the SGD server to host the application session:

By default, SGD load balances application sessions using the server that hosts the user session.

Application Load Balancing

Application load balancing is concerned with the following:

SGD Administrators manage application load balancing by defining the application servers that can run an application and by selecting the load balancing method to use.

Defining the Application Servers to Run the Application

You define the application servers that can run an application by assigning application server objects to the application object.

In the Administration Console, you do this on the Hosting Application Servers tab for the application. Alternatively, you can assign an application to an application server. You do this on the Hosted Applications tab for the application server object.

You can also assign groups of applications to an application server, or groups of application servers to an application. Groups are useful for creating pools of application servers, sometimes called application server farms, or applications.

In the Administration Console, you can also select and deselect the Application Start check box on the General tab for an application server object. This marks an application server as available or unavailable to run applications. This is useful, for example, to make a server temporarily unavailable during maintenance work.

Selecting the Load Balancing Method

You can select the load balancing method that SGD uses to determine the most suitable application server for the user.

In the Administration Console, you configure a default load balancing method on the Global Settings -> Performance tab. You can override the global load balancing method for an individual application by selecting a different method on the Performance tab for the application object.

By default, SGD uses a method that load balances applications by counting the number of application sessions each server is hosting through SGD and then selecting the server with the fewest sessions. SGD also provides methods for load balancing applications based on the true load of the application server when a user starts an application. This is called Advanced Load Management. To use Advanced Load Management, you must install the SGD Enhancement Module on every application server.

See How Application Load Balancing Works for details on how the load balancing method and other factors affect load balancing.

Load Balancing Groups

SGD uses load balancing groups to ensure that connections between SGD servers and application servers take place over high-speed links.

SGD’s Protocol Engines convert the native protocol, such as X11, which is used between the application server and the SGD server, into AIP, which is used between the SGD server and the client device. AIP is optimized for lower bandwidths, but native protocols are not.

If your network includes slow links, you can improve the performance of applications by using load balancing groups. You use load balancing groups to group SGD servers and application servers together. When a user runs an application, SGD tries to ensure that the Protocol Engine process runs on an SGD server in the same group as the application server. This works best when all the application servers and SGD servers in a group are connected by high-speed links.

In the Administration Console, you define the load balancing groups on the Performance tab for an SGD server or an application server. The load balancing group name is simply a string or a comma-separated list of strings. The name can be anything, for example the location in the world or a building code.

How Application Load Balancing Works

The purpose of application load balancing is to select the application server that gives the user the best performance for a particular application. When starting an application, SGD builds a list of candidate application servers using the application servers listed on the Hosting Application Servers tab for the application object. SGD then has to determine which of the candidates is the best one for the user. The decision takes into account the following factors:

The following sections describe how these factors, and your SGD configuration, affect the choice of application server.

Application Server Availability

When starting an application, SGD checks its list of candidate application servers to see if any of them are currently unavailable. If an application server is unavailable, it is removed from the list.

SGD Administrators can mark an application server as being unavailable by deselecting the Application Start check box on the General tab for the application server object in the Administration Console. You can do this, for example, to make an application server unavailable during maintenance work.

If you are using SGD Advanced Load Management, the load balancing service sends regular keep alive packets to SGD. If these packets stop, SGD considers the application server to be “out of contact” and treats the server as unavailable until the load balancing service makes contact again.

Load Balancing Groups

Load balancing groups are used to group SGD servers and application servers together. When a user runs an application, SGD tries to ensure that the Protocol Engine process runs on an SGD server in the same load balancing group as the application server. This works best when all the application servers and SGD servers in a group are connected by high-speed links.

See Load Balancing Groups for more detail.

Server Affinity

When starting an application, SGD takes into account whether the user is already running any applications on an application server. This is known as server affinity. Server affinity means that, if possible, SGD runs an application on the same application server as the last application started by the user.



Note - For server affinity to work efficiently, the applications must be associated with the same set of application servers.



Server affinity is expressed as a percentage. Currently only the following two values are allowed:

  • 0 – Any running applications do not affect the choice of application server.

  • 100 – Any existing application servers must be reused if they can run the selected application. This is the default value.

You change the server affinity value by running the following command:


$ tarantella config edit \
--tarantella-config-applaunch-appserveraffinity 0|100



caution icon

Caution - If you are using Windows applications, it is best not to change this value, as using multiple application servers causes problems, especially with roaming profiles. There might also be licensing implications for running different applications in a suite of applications on different servers.



The Relative Power of the Application Servers

SGD allows you to factor in the relative power of the application servers to the decision as to where to start an application.

The relative power is expressed as a percentage and by default all servers have a value of 100. By editing the weighting load balancing property for your servers, you can increase or decrease these weightings to increase or decrease the likelihood of SGD choosing an application server. For more details about weightings, see Tuning Application Load Balancing.

You can use the relative power of application servers to do the following:

  • Reduce the number of application sessions that are started on a particular server, for example, because it is used for other processes outside of SGD

  • Increase the number of application sessions that are started on a particular server, for example, because, although it has less CPU capacity, it has better Input/Output (I/O) capabilities

For more details on how the weighting is used, see the load calculations in The Application Server With the Least Load.

Example Relative Power Calculation 1

You have two application servers, london and paris. Paris has a weighting of 50 and london has a weighting of 100. If all the other conditions for starting applications are met and the servers currently have the same load, london is more likely to be chosen to run the application.

Example Relative Power Calculation 2

You have 100 application servers and you want to make just one of them “more powerful” than the others. Increase the weighting of that server to 200.

The Application Server With the Least Load

SGD supports several methods for selecting the application server with the least load.

You set a default method on the Global Settings -> Performance tab in the Administration Console. You can override the default by specifying a different method on the Performance tab for the application object. This allows you to load balance applications in different ways.

The following are the supported application load balancing methods:

  • Fewest Application Sessions

  • Least CPU Usage

  • Most Free Memory

The Least CPU Usage and Most Free Memory methods calculate the true load of the application server when a user starts an application. This is called Advanced Load Management. See How Advanced Load Management Works for more details.

Fewest Application Sessions

The Fewest Application Sessions method allows SGD to choose the application server which is currently running the fewest number of application sessions. It is based on a simple count of the number of application sessions hosted through SGD.

This method is the default.

If you use Advanced Load Management, the Fewest Application Sessions method is used as a fallback whenever there is a problem, for example if the application server load information is not available to the array when the application is started. This might happen, for example, if the primary SGD server is being restarted.

The application server load is calculated using the following formula:

number of application sessions x 100 /server weighting

Example Load Calculation Using Fewest Application Sessions

The following is an example of how SGD calculates the load using the Fewest Application Sessions method of application load balancing.

The application server london is currently hosting 10 application sessions and has a server weighting value of 100.

The application server paris is currently hosting 12 application sessions, and has a server weighting value of 100.

The load value for london is:

10 x 100/100 = 10

The load value for paris is:

12 x 100/100 = 12

Assuming the other conditions for starting an application are met, SGD chooses london to run the next two application sessions. If the server weighting value for london was decreased to 50, SGD chooses paris to run the next 8 application sessions, because london’s load is now 20 (10 x 100/50).

Least CPU Usage

The Least CPU Usage method allows SGD to choose the application server with the most CPU idle and is suitable for applications that require many processor cycles.

The method measures the application server’s load in terms of its CPU capabilities, measured in BogoMips, and by how much of its CPU is being used. These measurements are taken by the load balancing service.

The spare capacity is calculated using the following formula:

(BogoMips x CPU idle %) x weighting /100

Example Load Calculation Using Least CPU Usage

The following is an example of how SGD calculates the load using the Least CPU Usage method of application load balancing.

The application server london has a BogoMips measurement of 500, a server weighting value of 75 and has 25% CPU idle.

The application server paris has a BogoMips measurement of 100, a server weighting value of 100 and has 50% CPU idle.

The spare capacity for london is:

(500 x 25) x 75/100 = 9375

The spare capacity for paris is:

(100 x 50) x 100/100 = 5000

Assuming the other conditions for starting an application are met, london is chosen as the application server, even though paris is using less of its CPU and has a higher server weighting value.

Most Free Memory

The Most Free Memory method allows SGD to choose the application server with most free virtual memory and is suitable for applications that require a lot of memory.

The method measures the application server’s load by comparing the application server’s actual virtual memory with the amount of memory that is currently being used. These measurements are taken by the load balancing service.

The spare capacity is calculated using the following formula:

virtual memory free x weighting /100

Example Load Calculation Using Most Free Memory

The following is an example of how SGD calculates the load using the Most Free Memory method of application load balancing.

The application server london has a server weighting value of 100 and has 250 megabytes virtual memory free.

The application server paris has a server weighting value of 75 and has 500 megabytes virtual memory free.

The spare capacity value for london is:

250 x 100/100 = 250

The spare capacity value for paris is:

500 x 75/100 = 375

Assuming the other conditions for starting an application are met, paris is the chosen application server.

How Advanced Load Management Works

Advanced Load Management enables you to load balance applications based on either the amount of free memory, or the amount of free CPU, the application server has when the application is started. You can only load balance X applications, Windows applications, and character applications using these methods.

To use Advanced Load Management, you must install the SGD Enhancement Module on every application server. This installs a load balancing service which provides SGD with real-time information about the application server’s CPU and memory load. It also helps SGD to detect if an application server is unavailable, for example because it is being rebooted.

The following is an overview of how the load balancing service works:

  1. Whenever the primary SGD server is started, it builds a list of application servers that need to be considered for load balancing. The list is updated whenever a host is assigned to, or removed from, an application.

  2. The primary SGD server contacts each of the load-balanced application servers and requests initial load information. It does this by contacting the load balancing service on TCP port 3579 on each application server. Establishing contact also confirms that the application server is available to run applications.

  3. The primary SGD server sends an update to the secondary servers in the array. The update contains capacity values for each of the methods and information about the application servers that are not available.

  4. The load balancing service sends regular updates to the primary SGD server on User Datagram Protocol (UDP) port 3579. The updates take place even if the load does not change. The absence of a regular update helps SGD to detect whether an application server is available to run applications.

  5. The primary SGD server sends regular updates to the secondary servers in the array. The update contains capacity values for each of the methods and information about the application servers that are not available. The updates take place even if the load does not change.



    Note - The load balancing service always sends application server load data to the primary SGD server. If the primary server is not available, Advanced Load Management is not available and the secondary servers revert to the default session‐based load balancing instead.



  6. The primary or secondary SGD servers starts applications on the basis of the load information they receive in the updates.

Tuning Application Load Balancing

SGD Administrators can tune application load balancing by editing application load balancing properties. These properties affect how the load balancing service used for Advanced Load Management operates, and how SGD calculates the application server load. You can tune application load balancing globally and for individual application servers. See Editing Application Load Balancing Properties for details on how to edit the load balancing properties.

Before you tune application load balancing, make sure you have read and understood the following:

You can tune the following aspects of how application load balancing works:

This tuning is described in the following sections.



caution icon

Caution - With the exception of tuning an application server’s relative power, this tuning only applies if you are using Advanced Load Management.



Application Server’s Relative Power

The weighting property allows you to factor in the relative power of the application servers to the decision SGD takes as to where to run an application. This is discussed in The Relative Power of the Application Servers.

Load Balancing Listening Ports

The primary SGD server in the array contacts the SGD load balancing service on an application server on TCP port 3579. This is controlled by the listeningport property.

The load balancing service sends updates to the primary SGD server on UDP port 3579. This is controlled by the probe.listeningport property.

These ports are registered with the Internet Assigned Numbers Authority (IANA) and are reserved for use only by SGD. Only change these properties if Sun Support asks you to. You must open these ports if you have a firewall between the primary SGD server and the application servers.

SGD Requests Updates From an Application Server

The connectretries property is the number of times the primary SGD server tries to connect to an application server to request load updates. The interval between each attempt is controlled by the shorttimeout property. If the attempts to connect fail, the SGD server waits for the period of time controlled by the longtimeout property before trying again.

For example, using the defaults for these properties, the primary SGD server makes 5 attempts (connectretries) to contact the application server at 20 second intervals (shorttimeout). If all 5 attempts fail, SGD waits 600 seconds (longtimeout) before making 5 more attempts at 20 second intervals.

You might want to change the timeout properties, for example, if an application server takes a long time to reboot.

The scaninterval property controls the period of time between scans of the SGD server’s list of load-balanced application servers. The scan checks for the application servers that need to be contacted to request a load update (connectretries).

The sockettimeout property controls how long it is before an SGD server gets an error by trying to contact the load balancing service when there is no data available.

Frequency of the Load Calculation

The probe.samplerate and probe.windowsize properties control how often the load balancing service measures the application server’s average load.

For example, the probe.samplerate is 10 seconds and the probe.windowsize is 5. After 50 seconds (5 x 10), the 5 measurements needed to calculate the average have been taken. After a further 10 seconds, the load balancing service takes a new measurement, discards the oldest measurement and then calculates a new average load.

You can increase and decrease the frequency of the calculation depending on how often you expect the application server load to change. For example, if users start applications at the start of the day and then close them at the end of the day, you might want to decrease the frequency of the load calculation. However, if users repeatedly start and stop applications, you might want to increase the frequency of the load calculation.

Frequency of Updates to the Primary SGD Server

The replyfrequency property controls the interval at which the load balancing service send updates to the primary SGD server.

The percentagechange property controls the minimum percentage change in CPU or memory use that must be reported to the primary SGD server. The load balancing service sends these updates as soon as the percentage change occurs. For example if an application server is running at 30% CPU load and the percentchange value is 10, an update occurs when the load is either 20% or 40%. The load balancing service takes into account sudden “spikes” of activity and also makes adjustments when, for example a server reaches 81% CPU load and the percentagechange value is 20%.

The replyfrequency updates are sent even if the load does not change and even if there has been a percentagechange update. The basis for the percentage change calculation is reset every time there is a replyfrequency update.

If there is no update from an application server for updatelimit x replyfrequency seconds, SGD considers the application server to be “out of contact”. This means the application server is marked as unavailable to run applications until the SGD server can re-establish contact with it.

Reliability of CPU and Memory Data

SGD considers the CPU and memory data it receives to be too unreliable if there has been no update from the application server for updatelimit x replyfrequency seconds.



Note - The load balancing service sends updates even if the load does not change.



If the data is unreliable, the data is ignored when making the decision on where to run an application. The net effect of this is to make the application server the last in the queue so that it can only be used to run applications if no other server is available or suitable.

Frequency of Updates to Array Members

The primary SGD server sends CPU and memory load updates to the other members of the array every maxmissedsamples x replyfrequency/2 seconds. This update takes place even if the load does not change.

If a secondary SGD server misses an update, it considers the load data it has to be unreliable and reverts to the Fewest Application Sessions method of load balancing. It uses this method until it receives a new update.

Editing Application Load Balancing Properties

You tune SGD application load balancing by editing application server load balancing properties. The properties are stored in a properties file, which you can edit with a text editor. There are three properties files, as follows:

This section describes how you edit the properties files and what properties are available. For detailed information on how to use the properties, see Tuning Application Load Balancing.



caution icon

Caution - Edit these properties with care as it can cause applications to fail to start.



The Global Load Balancing Properties File

The global load balancing properties file contains the default load balancing properties for all the SGD servers in an array.

The file is /opt/tarantella/var/serverconfig/global/tier3lb.properties.



caution icon

Caution - Only edit these properties on the primary SGD server in the array. The primary copies the amended properties file to the secondary servers.



In the tier3lb.properties properties file, the properties are prefixed with tarantella.config.tier3lb, for example tarantella.config.tier3lb.weighting.

The following table lists the properties you can change, and gives the default value of the property when SGD is first installed. The table also explains what each property is used for.


Property Default Value Purpose
connectretries 3 The number of times the SGD server tries to connect to the application server to request CPU and memory usage updates.
listeningport 3579 The UDP port the SGD server uses to listen for data sent by the load balancing service.
longtimeout 900 The pause in seconds between groups of attempts by the SGD server to connect to the application server.
maxmissedsamples 20 The number of missed samples used to calculate whether the CPU and memory data for the application server is too unreliable to be used.
probe.listeningport 3579 The TCP port the load balancing service uses to listen for requests from SGD servers, for example, when to start sending updates.
probe.percentchange 10 The minimum percentage increase or decrease in CPU and memory use that must be reported to the SGD server.
probe.replyfrequency 30 The interval in seconds at which the load balancing service sends CPU and memory measurements to the SGD server. The minimum value for this property is 2.
probe.samplerate 15 The interval in seconds between CPU and memory measurements. The minimum value for this property is 1.
probe.windowsize 3 The number of CPU and memory measurements used to calculate the CPU and memory average. The minimum value for this property is 1.
scaninterval 60 The interval in seconds between scans of the SGD server’s list of load-balanced application servers.
shorttimeout 60 The interval in seconds between attempts by the SGD server to connect to the application server.
sockettimeout 5 The socket timeout in seconds.
updatelimit 5 The limit used to calculate when the load balancing service has stopped sending updates.
weighting 100 The weighting of load measurements relative to the other application servers.

The following properties also appear in the tier3lb.properties properties file, but they must not be changed:

tarantella.config.name=tier3lb
tarantella.config.type=server

The Application Server Load Balancing Properties File

You can override some of the global load balancing properties by creating a load balancing properties file for a particular application server. You have to manually create this file as described in How to Create an Application Server Load Balancing Properties File.

The global properties you can override are the following:

  • probe.listeningport

  • probe.percentchange

  • probe.replyfrequency

  • probe.samplerate

  • probe.windowsize

  • weighting

In the server-specific properties file, the properties are prefixed with tarantella.config.tier3hostdata, for example tarantella.config.tier3hostdata.weighting.

procedure icon  How to Create an Application Server Load Balancing Properties File

Ensure that no users are logged in to the SGD server, and that there are no application sessions, including suspended application sessions, running on the SGD server.

  1. Log in as superuser (root) on the primary SGD server.



    caution icon

    Caution - Only create the load balancing properties file on the primary SGD server in the array. The primary copies the file to the secondary servers.



  2. Change to the /opt/tarantella/var/serverconfig/global/t3hostdata directory.

  3. Create the load balancing properties file.

    Copy the template.properties file to a file called hostname.properties in the same directory, where hostname is the name of the application server, for example, paris.indigo‐insurance.com.properties.

  4. Edit the load balancing properties file.

    1. Open the properties file in a text editor.

    2. Add the fully qualified name of the application server.

      Find the line containing the tarantella.config.tier3hostdata.name property.

      After the “=”, type the fully qualified name of the application server.

      Enclose the name in quotes and escape each part of the host name with a backslash. For example:

      ".../_ens/o\=Indigo Insurance/cn\=paris"

    3. Configure the server-specific properties.

      Uncomment the lines, by deleting the “#”, that contain the properties you want to be override.

      Only uncomment the properties that you want to be different from the global defaults.

      Change the values of the properties you want to override.



      Tip - The template.properties file contains comments to help you create a server-specific file.



    4. Save the changes and close the file.

  5. Do a warm restart of the primary SGD server.


    # tarantella restart sgd --warm
    

The Load Balancing Service Properties File

The load balancing service properties file contains the settings that are used when the load balancing service is first started, or whenever the service is restarted, on a UNIX or Linux platform application server.



caution icon

Caution - Only make changes to these properties if you have been asked to by Sun Support, or if you change the physical or virtual memory of the application server and you have not reinstalled the SGD Enhancement Module.



The load balancing services properties file is: /opt/tta_tem/var/serverconfig/local/tier3loadbalancing.properties.

If you change these properties, you must manually stop and restart the load balancing service.

The properties you can override are the following:

  • probe.listeningport

  • probe.percentchange

  • probe.replyfrequency

  • probe.samplerate

  • probe.windowsize

  • weighting

In the load balancing service properties file, the properties are prefixed with tarantella.config.tier3loadbalancing, for example tarantella.config.tier3loadbalancing.weighting.


SGD Web Server

This section describes how to configure the web server that is included with SGD. This web server is called the SGD web server.

This section includes the following topics:

Introducing the SGD Web Server

You must have a web server running on each host on which SGD is installed. When you install SGD, the SGD web server is also installed.

The SGD web server is a web server that has been preconfigured for use with SGD. The SGD web server consists of the following components.


Component Version
Apache HTTP Server 2.2.10
OpenSSL 0.9.8i
mod_jk 1.2.25
Apache Jakarta Tomcat 6.0.18
Apache Axis 1.4



Note - The Apache web server includes all the standard Apache modules as shared objects.



If you have an existing web server on the SGD host, this is not affected by the SGD web server, as the SGD web server listens on a different port.

You can configure the SGD web server using standard Apache directives. See the Apache documentation for details.

You can control the SGD web server independently of the SGD server, using the tarantella start webserver, tarantella stop webserver, and tarantella restart webserver commands.

Using Another Web Server With SGD

When you install SGD, you install the SGD web server. This web server is preconfigured for use with SGD and it is best to use it.

If you want to use your own web server with SGD, you can do so. However, as client applications such as the SGD webtop use the Simple Object Access Protocol (SOAP) protocol over HTTP to access the services provided by an SGD server, you must continue to run the SGD web server, even if you use your own web server.

To use your own web server for the webtop, you need a web server and a JSP technology container. This is because the webtop is a JSP software application.

Once you have a working web server and JSP technology container, follow the instructions for relocating the webtop in Relocating the Webtop.

Securing the SGD Web Server

By default, the SGD web server is configured to be a secure HTTPS web server and to share the SGD server SSL certificate used for SGD security services. See Using HTTPS Connections to the SGD Web Server.

If you require enhanced security, a more secure version of the httpd.conf Apache configuration file used by the SGD web server is supplied. See The httpd.conf.secure File for more details about this file.

The httpd.conf.secure File

The httpd.conf.secure file is an Apache server configuration file that configures the SGD web server for enhanced security. The file is included with the SGD distribution, at /opt/tarantella/webserver/apache/2.2.10_openssl‑0.9.8i_jk1.2.27/conf/httpd.conf.secure on the SGD host.

The httpd.conf.secure file provides the following additional security features, compared to the standard httpd.conf file used by the SGD web server:

  • Apache modules that are not used by SGD are disabled

  • Access to the /cgi-bin directory on the SGD web server is not allowed

To use httpd.conf.secure on an SGD server that has previously been secured, you must first disable security on the SGD server, before installing the httpd.conf.secure file. You can then enable security services for the SGD server, as described in How to Enable SGD Security Services for an SGD Server.



caution icon

Caution - Do not use httpd.conf.secure if you have used the tarantella security enable command to configure security automatically on the SGD server.




Administration Console

This section describes how SGD Administrators can run and configure the Administration Console.

This section includes the following topics:

Running the Administration Console

This section describes how to run the Administration Console. It also includes details of how to avoid some common problems when using the Administration Console.

Supported Browsers for the Administration Console

To display the Administration Console, you can use any browser that is supported by SGD, apart from Safari. See Supported Client Platforms for details of the supported browsers for SGD. The browser must have the JavaScript programming language enabled.



caution icon

Caution - When using the Administration Console, do not use the browser’s Back button. Instead, use the Jump to Object View and Jump to Navigation View links, or the Object History list, to navigate through the Administration Console pages.



Starting the Administration Console

The Administration Console works best when you run it on the primary SGD server in the array.

You can start the Administration Console in the following ways:

  • Click the Administration Console link on the webtop of an SGD Administrator.

  • Click the Launch the Sun Secure Global Desktop Administration Console link on the SGD web server Welcome Page at http://server.example.com, where server.example.com is the name of an SGD server.

  • Go to the http://server.example.com/sgdadmin URL.



Note - The Administration Console is for SGD Administrators only. To use the Administration Console you must log in as, or be logged in as, an SGD Administrator.



Deploying the Administration Console on Other Web Application Containers

The Administration Console is only supported when used with the SGD web server.

The Administration Console ships with a web application archive (WAR) file, sgdadmin.war. Using this file to redeploy the Administration Console on another web application server is not supported.

Avoiding SGD Datastore Update Problems

You can perform operations on the SGD datastore, such as creating new objects and editing object attributes, using the Administration Console from any SGD server in the array.

When you edit the SGD datastore, the changes you make are sent to the primary SGD server. The primary SGD server then replicates these changes to all secondary servers in the array.

By running the Administration Console from the primary SGD server, you can avoid problems due to the following:

  • Slow network. If the network is slow, “Object not found” or “Object not created” errors can be returned. Also, problems with stale data can occur, where configuration changes are not shown correctly.

  • Primary down. If the primary server is down, or unavailable, SGD datastore changes are not applied.

Performing Array Operations Using the Administration Console

The following limitations apply when using the Administration Console to perform array operations, such as array joining or array detaching:

  • Use the primary SGD server. Running the Administration Console on the primary server avoids data replication problems. See also Avoiding SGD Datastore Update Problems.

  • All servers involved in an array operation must be up. For example, you cannot use the Administration Console to detach a secondary server that is down. Instead, use the tarantella array detach command.

Displaying Online Help Over HTTPS Connections

The Administration Console uses the JavaHelptrademark software to display online help. However, the online help is disabled when HTTPS connections to the SGD web server are enabled.

To run JavaHelp over an HTTPS connection, the Certificate Authority (CA) certificate truststore must contain the CA certificate, or the CA certificate chain, used to sign the SGD web server SSL certificate. By default, the SGD web server uses the same SSL certificate as the SGD server. See The CA Certificate Truststore for details.

Administration Console Configuration Settings

The deployment descriptor for the Administration Console web application contains settings that control the operation of the Administration Console. The deployment descriptor is the following file:

/opt/tarantella/webserver/tomcat/6.0.18_axis1.4/sgdadmin/WEB-INF/web.xml

This section describes the settings in the deployment descriptor that you might want to configure. Most of the settings are context parameters, contained in <context-param> elements. You must not change any other settings in the web.xml file.

When working with deployment descriptor settings, note the following:

Number of Search Results

The com.sun.tta.confmgr.DisplayLimit context parameter enables you to configure the maximum number of search results you can display in the Administration Console. The default is 150. If there are more results than the display limit, the Administration Console displays a message. Increasing the display limit can have an effect on performance. Set the display limit to 0 to see unlimited search results.

Synchronization Wait Period

The com.sun.tta.confmgr.ArraySyncPeriod context parameter is only used if you are running the Administration Console from a secondary server, and you create or edit objects in the SGD datastore. This parameter enables you to configure the period of time, in milliseconds, that the Administration Console waits for changes to be copied across the array before proceeding. The default value is 250. The Administration Console waits for twice this setting, a default of 0.5 seconds, before proceeding.

Searching and Displaying LDAP Data

The com.sun.tta.confmgr.LdapSearchTimeLimit context parameter enables you to configure the maximum time, in milliseconds, to allow for a search of a Lightweight Directory Access Protocol (LDAP) directory. The default is 0, which means the search time is unlimited. Only change this context parameter if you have particularly slow LDAP directory servers.

The following context parameters are used to filter the display of LDAP data, when you select Local + LDAP in the Repository list in the Administration Console:

  • Filters used by the navigation tree. These are the following context parameters:

    • com.sun.tta.confmgr.LdapContainerFilter

    • com.sun.tta.confmgr.LdapUserFilter

    • com.sun.tta.confmgr.LdapGroupFilter

  • Filters used when you search an LDAP directory. These are the following context parameters:

    • com.sun.tta.confmgr.LdapContainerSearchFilter

    • com.sun.tta.confmgr.LdapUserSearchFilter

    • com.sun.tta.confmgr.LdapGroupSearchFilter

  • Filters used when you load the LDAP assignments on the Assigned Applications tab for a user profile. This is the com.sun.tta.confmgr.LdapMemberFilter context parameter.

These context parameters contain the definitions of what the Administration Console considers as LDAP containers, users, and groups. You might want to change these filters to improve performance, or to change the definition of these LDAP object types to match those used in your LDAP directory. To avoid inconsistencies, if you change a filter for the navigation tree, you must also change the filter used for the LDAP search.

Session Timeout

The session-timeout setting defines the period of time after which the user is logged out if there is no activity, meaning no HTTP requests, in the Administration Console. The default setting is 30 minutes, to ensure unattended Administration Console sessions are not left open indefinitely.



Note - The session-timeout setting is independent of the timeout attribute for inactive user sessions, tarantella-config-array-webtopsessionidletimeout.



Securing Access to the Administration Console

Because the Administration Console is a web application, you can control which client devices are allowed to access it.For example, you can do this by configuring the SGD web server to use the Apache <Location> directive, as in the following example:

<Location /sgdadmin>
   Order Deny,Allow
   Deny from all
   Allow from 129.156.4.240
</Location> 

In this example, only client devices with an IP address of 129.156.4.240 are allowed to access the /sgdadmin directory on the SGD web server. The /sgdadmin directory contains the home page of the Administration Console.

For more information on how to configure the <Location> directive, check the Apache documentation.


Monitoring and Logging

This section describes the SGD datastore, how to monitor user activity, and how to configure logging.

This section includes the following topics:

The SGD Datastore

The SGD servers in an array share information. Each SGD server knows:

The collection of information is known as the datastore.

Information about users, applications, application servers, and webtops is stored on disk and is known as the local repository. Information about user and application sessions is stored in memory.

The datastore is organized into namespaces which are displayed and used on the command line and log files. The general structure is .../namespace/name-within-namespace. The ... indicates the root of the datastore. The namespace indicates the source of the information, such as DNS. After the namespace, names are written using whichever naming scheme is appropriate to the namespace. Names are written like file system paths (slash-separated and top-down).

The following are some commonly used namespaces.


Namespace Description Example
Local SGD objects in the local repository .../_ens/o=Indigo Insurance/ou=Marketing/cn=Cust-o-Dat
LDAP Objects in an LDAP directory .../_service/sco/tta/ldapcache/cn=Cust-o-Dat,ou=Marketing,o=Indigo Insurance
DNS Machines on the network .../_dns/verona.indigo-insurance.com

User Sessions and Application Sessions

This section describes the differences between user sessions and application sessions in SGD. Using the Administration Console and the command line to monitor and control user and application sessions is also covered.

This section includes the following topics:

User Sessions

A user session begins when a user logs in to SGD and ends when a user logs out of SGD. User sessions are hosted by the SGD server the user logs in to. The user name and password they type determine the type of user they are. See Chapter 2 for more details about user authentication.

If a user logs in and they already have a user session, the user session is transferred to the new SGD server and the old session ends. This is sometimes called session moving, or session grabbing.

User sessions can be standard sessions or secure sessions. Secure sessions are only available when SGD security services are enabled. See Securing Connections Between Client Devices and SGD Servers for more details.

In the Administration Console, you can list user sessions as follows:

  • The Sessions tab, in Navigation View, shows all the user sessions that are running on all SGD servers in the array

  • The User Sessions tab for an SGD server shows all the user sessions that are hosted by that SGD server

  • The User Sessions tab for a user profile shows all the user sessions associated with the user profile

The Sessions tab and User Sessions tab enable you to select and end user sessions. The User Sessions tab enables you to view further details about the user session. For example, the information that the SGD Client detects about the client device.

On the command line, you use the tarantella webtopsession command to list and end user sessions.

Idle User Session Timeout

You can configure an idle timeout period for inactive user sessions. User sessions are suspended if there has been no activity on the AIP connection between the SGD Client and the SGD server for the specified period.

Activity on the following devices has no effect on the idle timeout period:

  • Serial ports

  • Smart cards

  • Audio

You specify the idle timeout attribute using the following command:


$ tarantella config edit \
‐‐tarantella-config-array-webtopsessionidletimeout secs

Replace secs with the timeout value, measured in seconds. A setting of 0 turns off the user session idle timeout feature. This is the default setting.

Application Sessions

An application session begins when a user starts an application and ends when the application exits. Each application session corresponds to an application currently running through SGD.

An application session can be hosted by any SGD server in the array. This might not be the same SGD server that the user logged in to, see Arrays.

Each application session has a corresponding Protocol Engine process. The Protocol Engine handles the communication between the client device and the application server. The Protocol Engine also converts the display protocol used by the application to the AIP, which is understood by the SGD Client running on the client device.

You can use application session load balancing to spread the load of the Protocol Engines among the SGD servers in the array. See Application Session Load Balancing for more details.

Some applications can be configured to keep running, even when they are not displayed. These are called resumable applications.

Each application object has an Application Resumability attribute that determines the application’s resumability behavior. Applications can have one of the following Application Resumability settings.


Setting Description
Never The application exits when the user logs out of SGD. You cannot suspend or resume applications that are non-resumable.
During the User Session The application continues to run until the user logs out of SGD. While they are logged in, the user can suspend and resume these applications.
General The application continues to run even after the user has logged out of SGD. When the user logs in again, they can click the Resume button to display the running application again.

If an application is resumable, it is resumable for a period of time, specified by a timeout. If the SGD Client exits unexpectedly, the timeout period is the configured timeout plus 20 minutes.

Resumable applications are useful for the following reasons:

  • Applications that take a long time to start can be left running, even after users have logged out of SGD

  • Mobile users can leave applications running while they travel

  • Users can easily recover from browser or other crashes

In the Administration Console you can list application sessions as follows:

  • The Application Sessions tab for an SGD server shows all the application sessions that are hosted by that server

  • The Application Sessions tab for a user profile shows all the application sessions associated with the user profile

  • The Application Sessions tab for an application server shows all the applications that are running on that application server

The Applications Sessions tab enables you to view details about each application session. You can also end and shadow application sessions. Shadowing a session enables you and the user see and interact with the application at the same time.

See Using Shadowing to Troubleshoot a User’s Problem for more details about shadowing application sessions.



Note - You can only shadow Windows applications and X applications. The application sessions must not be suspended.



On the command line, you use the tarantella emulatorsession command to list and end user sessions.

Anonymous Users and Shared Users

There are two special cases, as follows:

To be able to distinguish between these users, SGD assigns shared users and anonymous users a temporary user identity when they log in. This has the following effects:

  • User sessions do not transfer if the user logs in to SGD more than once

  • Application sessions end as soon as the user session ends, regardless of the application’s Application Resumability setting

  • If the user does not log out, server resources are consumed

Using Log Filters to Troubleshoot Problems With an SGD Server

When you first install SGD, the default log filters log all errors on the SGD server. If you want to obtain more detailed information, for example to troubleshoot a problem, you can set additional log filters.

You can set additional log filters in the following ways:

Each log filter has the form:

component/subcomponent/severity:destination

The options for each part of the filter, and how you view the log output, are described in the following sections.



Note - Log filters can create large amounts of data. It is good practice to set as specific a filter as possible and then remove the filter when you have finished with it.



Selecting a Component and Subcomponent

Selecting a component and subcomponent enables you to choose the area of information you want to log from the SGD server.

The following table shows the available component/subcomponent combinations and an explanation of the kind of information produced.


Component and Subcomponent Information Provided
audit/glue Audit of changes made to the SGD server configuration, or to your local repository configuration, and who made the changes.

For example, you can use this to find out who made changes to a user profile object.

audit/license License use across an array of SGD servers.

For example, you can use this to find out why the use of licenses is not being recorded.

audit/session Starting and stopping user sessions and application sessions.

For example, you can use this to find out how long a user had a running application session.

cdm/audit Authorization of SGD user for client drive mapping (CDM) purposes.

For example, you can use this to find out whether a user’s credentials are causing CDM to fail.

cdm/server Information about CDM services.

For example, you can use this to find out whether a client connection error is causing CDM to fail.

common/config How SGD server configuration is stored and copied across the array.

For example, you can use this to find out why a global setting configuration change is not being applied to an SGD server.

metrics/glue Memory and timings.

For example, you can use this to find out how long it took to run an SGD command.

metrics/soap The SOAP component of Tomcat’s SOAP proxy.

For example, you can use this to trace how long it took a SOAP request to finish.

server/ad Active Directory authentication.

For example, you can use this to find out why an Active Directory user cannot log in.

server/billing SGD billing services.

For example, you can use this to find out why billing data is being lost.

server/common General SGD information.

For example, you can use this to troubleshoot DNS errors.

server/config Changes to SGD server configuration.

For example, you can use this to log changes to SGD server configuration or to find out if the configuration has become corrupt.

server/csh The SGD client session handler.

For example, you can use this to find out why a user can not restart an application session.

server/deviceservice Mapping of users to accessible device data.

For example, you can use this to find out why a user can not access client drives.

server/diskds Information about the local repository.

For example, you can use this to get information about corrupt objects or inconsistencies in the local repository.

server/failover Information about array failover.

For example, you can use this to troubleshoot problems with an SGD array where the primary server is unavailable.

server/glue The protocol used for communication between SGD servers.

For example, you can use this to find out why SGD servers cannot communicate.

server/install Installation and upgrades.

For example, you can use this to investigate problems with an installation.

server/kerberos Windows Kerberos authentication.

For example, you can use this to find out why an Active Directory user cannot log in.

server/launch Starting or resuming applications.

For example, you can use this to find out why a user cannot start an application.

server/ldap Connections to an LDAP server.

For example, you can use this to find out why an LDAP user cannot log in.

server/loadbalancing User session and application load balancing.

For example, you can use this to find out why an SGD server is not selected to host application sessions.

server/logging Logging.

For example, you can use this to find out why log messages are not being written to a file.

server/login Log in to SGD.

For example, you can use this to find out which authentication mechanism authenticated a user and the user profile used.

server/mupp The SGD MUltiplePlexing Protocol (MUPP) protocol.

Only use this filter if Support ask you to.

server/printing SGD printing services.

For example, you can use this to find out why print jobs are failing.

server/replication Copying data between SGD servers in an array.

For example, you can use this to find out why data has not been copied between array members.

server/securid Connections to SecurID RSA Authentication Manager.

For example, you can use this to find out why SecurID authentication is not working.

server/security Secure SSL-based connections.

For example, you can use this to find out why the SSL Daemon is not running.

server/server The SGD server component.

For example, you can use this to troubleshoot SGD server failures, such as Java™ technology runtime exceptions which are not logged elsewhere.

server/services Internal SGD server services.

For example, you can use this to find out why a service is failing.

server/session User sessions.

For example, you can use this to find out why a session failed to suspend.

server/soap SOAP bean interface.

For example, you can use this to diagnose problems with the SOAP beans.

server/soapcommands SOAP requests.

For example, you can use this to log the SOAP requests received.

server/tier3loadbalancing Application server load balancing.

For example, you can use this to find out why an application server is not being selected to run an application.

server/tokencache Authentication token cache.

For example, you can use this to find out why an authentication token is not being created for a user.

server/tscal Windows Terminal Services Client Access Licenses (CALs) for non-Windows clients.

For example, you can use this to find out why a non-Windows client does not have a CAL.

server/webtop Webtop content, if you are using Directory Services Integration.

For example, you can use this to find out why an application is not appearing on a user’s webtop.


Selecting the Severity

You can select one of the following levels of severity for each log filter.


Severity Description
fatalerror Logs information on fatal errors. Fatal errors stop the SGD server from running. When you first install SGD, all fatal errors are logged by default.
error Log information on any errors that occur. When you first install SGD, all errors are logged by default.
warningerror Log information on any warnings that occur, for example if system resources are running low. When you first install SGD, all warnings are logged by default.
info Informational logging. Useful for problem solving and identifying bugs.
moreinfo Verbose informational logging.
auditinfo Logs selected events for auditing purposes, for example changes to SGD server configuration. For details see, Using Log Filters for Auditing.

The fatalerror severity level produces the least amount of information. The moreinfo severity level produces the most information.

Selecting a severity level is not cumulative. For example, selecting info does not mean you also see warningerror or fatalerror log messages.

To log more than one level of severity, use a wild card.

Using Wildcards

You can use a wildcard (*) to match multiple components, subcomponents, and severities.

For example, to log all warning, error, and fatal error messages for printing, you can use a server/printing/*error log filter.



Note - If you use a wildcard on the command line, you must enclose the filter in straight quotation marks, to stop your shell from expanding them.



Selecting a Destination

When selecting a destination for the logs, you can specify that the output goes to one of the following destinations:

  • A log file

  • A log handler

These destinations are described in the following sections.

Using Log Files

If you direct the output to a log file, you can output to the following types of file:

  • filename.log

    SGD formats this log output so that it is easy to read.

    This format is required by the tarantella query errlog command. This command only searches log files that have names that end error.log.

  • filename.jsl

    SGD formats this log output for automated parsing and searching.

    This format is required by the tarantella query audit command.

The file extension of the destination file controls the format of the file.

You can also create a separate log file for each process ID, by including the %%PID%% placeholder in the file name.

The log files are output in the /opt/tarantella/var/log directory. You cannot change the location of the log files, but you can use a symbolic link to redirect the logs to a different location. Alternatively, you can use the syslog log handler described in Using Log Handlers.

Using Log Handlers

A log handler is a JavaBeanstrademark component used as the destination for the log messages. When specifying a log handler, you must use its full name. SGD provides the following log handlers:

  • ConsoleSink. The ConsoleSink log handler writes log messages in a easy-to-read format to standard error. This log handler is enabled by default and logs all fatal errors.

    The full name of this log handler is:

    .../_beans/com.sco.tta.server.log.ConsoleSink

  • SyslogSink. The SyslogSink log handler writes log messages to the UNIX or Linux platform syslog facility.

    The full name of this log handler is:

    .../_beans/com.sco.tta.server.log.SyslogSink

Examples of Using Log Filters

The following are some examples of commonly used log filters:

  • To debug user logins:

    server/login/*:login%%PID%%.log
    server/login/*:login%%PID%%.jsl

  • To troubleshoot CDM:

    cdm/*/*:cdm%%PID%%.log
    cdm/*/*:cdm%%PID%%.jsl
    server/deviceservice/*:cdm%%PID%%.log
    server/deviceservice/*:cdm%%PID%%.jsl

  • To troubleshoot printing problems:

    server/printing/*:print%%PID%%.log
    server/printing/*:print%%PID%%.jsl

  • To get timing measurements for server performance:

    metrics/*/*info:metrics.log
    metrics/*/*info:metrics.jsl

  • To send all warnings, errors, and fatal errors to syslog:

    */*/*error:.../_beans/com.sco.tta.server.log.SyslogSink

Viewing Log Output

To view the log output, you can do either of the following:

  • Open the .log files in a viewer or text editor

  • Use the tarantella query command

If you use the tarantella query command, use the following command options:

  • tarantella query errlog – To see only the errors and fatal errors for specific SGD server components

  • tarantella query audit – Searches the logs for any messages relating to a person, an application, or an application server



Note - You can only use these commands to view the log output until the logs are archived. You configure archiving when you install SGD, but you can change the settings at any time by running the tarantella setup command.



Using Log Filters for Auditing

SGD enables you to set log filters to provide an audit of the following system events:

To audit these events, you must set a */*/*auditinfo log filter.

You can use any of the standard destinations as a destination for the output, but you must direct the output to a .jsl file if you want to view the audit information from the command line.

See Using Log Filters to Troubleshoot Problems With an SGD Server for more information about setting log filters.



Note - Log output is only created while an SGD server is actually running. If an SGD server is stopped, only the UNIX system root user can perform any of the auditable events.



For each of the events, the log filter records following:

Viewing Audit Log Information

You can use any of the standard methods for viewing the log output. However, the following command is the most useful:


# tarantella query audit --format text|csv|xml --filter "filter"

If you select the text format, SGD formats the log output so that it is easy to read on screen, but it does not show every detail logged. Using the csv format shows every detail logged, but it is only suitable for outputting to a file.

The "filter" is an RFC2254-compliant LDAP search filter. The command searches the log fields in the log files for matching entries to display. For auditing purposes, the most useful log fields are shown in the following table.


Log Field Description
log-category For auditing purposes, the log-category is always *auditinfo, but this can be any of the standard log filter component/subcomponent/severity settings.
log-date The system date and time when the event took place.

The format is yyyy/MM/dd HH:mm:ss.SSS.

log-event The name of the event.
log-ip-address The IP address of a client or server associated with an event.
log-keyword The keyword identifier for the auditable event.
log-localhost The peer DNS name of the SGD server where the event took place.
log-pid The process ID of the event.
log-security-type The type of security used on a connection, std or ssl.
log-systime The system Cordinated Universal Time (UTC) time, in milliseconds, when the event took place.
log-tfn-name The full name of an object associated with an event.

For example, starting an application session might record the name of the user, the application, and the application server.




Note - A complete list of all the log fields is available in the /opt/tarantella/var/serverresources/schema/log.at.conf schema file.



The following table below shows all the log-keywords, and their corresponding log-events, together with a description of the event.


Log-Keyword Log-Event Description
createFailure createFailure A user tried to create an object in the local repository but failed.
createSuccess createSuccess A user created an object in the local repository.
deleteFailure deleteFailure A user tried to delete an object in the local repository but failed.
deleteSuccess deleteSuccess A user deleted an object in the local repository.
loginFailure loginResultReconnect The SGD server requested the client to reconnect on a different port.
loginFailure loginResultFailed None of the enabled authentication mechanisms authenticated the user.
loginFailure loginResultRejected User was denied a login by a login filter. For example, this might be because logins are currently not enabled for that particular server, or because the user is currently not allowed to log in.
loginFailure loginResultDisabled The SGD server is not currently accepting connections.
loginFailure loginResultNoAmbig An ambiguous login failed because the SGD server does not support ambiguous logins.
loginFailure loginResultAmbiguous An ambiguous login failed because the user did give enough disambiguation information.
loginFailure loginResultAnonymous An anonymous login failed because the SGD server does not support anonymous logins.
loginFailure loginResultNoSecurity Login failed because the user requires a secure connection, but the connection was made to the standard port.
loginFailure loginResultUnresolveable Login failed because the SGD server was unable to resolve which user had logged in.
loginFailure loginResultUnknown Login failed because the SGD server was unable to process an unexpected login result.
loginSuccess webtopSessionStartedDetails Started a user session for a user.
logout webtopSessionEndedDetails Stopped a user session for a user.
modifyFailure modifyFailure A user tried to change an object in the local repository, to change global settings, or to change the configuration of an SGD server but failed.
modifySuccess modifySuccess A user changed an object in the local repository, changed global settings, or changed the configuration of an SGD server.
renameFailure renameFailure A user tried to rename an object in the local repository but failed.
renameSuccess renameSuccess A user renamed an object in the local repository.
serverStart serverStart The SGD server was started.
serverStop serverStop The SGD server was stopped.
sessionEnded sessionEndedDetails Stopped an application session for a user.
sessionStarted sessionStartedDetails Started application session for a user.
sslStart securitySSLStart Started SGD security (SSL) services.
sslStop securitySSLStop Stopped SGD security (SSL) services.

Examples of Using Log Filters for Auditing

To search for failed log in attempts, use the following filter:

--filter "(&(log-category=*auditinfo)(log-keyword=loginFailure))"

To search for changes to made to the SGD server configuration by the Administrator Bill Orange, use the following filter:

--filter "(&(log-category=*auditinfo)(log-keyword=modifySuccess)(log-tfn-name=.../ens/o=Indigo Insurance/ou=IT/cn=Bill Orange))"

Using Log Filters to Troubleshoot Problems With Protocol Engines

When you first install SGD, the default log filters record all errors for protocol engines (PEs). To obtain more information about PE activity, you can set additional PE log filters.

PE log filters can be set for individual PEs, and for the Protocol Engine Manager (PE Manager) process. You configure a PE log filter by setting one of the attributes shown in the following table.


PE Filter Attribute Protocol Engine
--tarantella-config-auxserver-logfilter PE Manager
--tarantella-config-execpeconfig-logfilter Execution Protocol Engine
--tarantella-config-xpeconfig-logfilter X Protocol Engine
--tarantella-config-tpeconfig-logfilter Character Protocol Engine
--tarantella-config-ppeconfig-logfilter Print Protocol Engine
--tarantella-config-cpeconfig-logfilter Channel Protocol Engine

You can only set a PE log filter from the command line. Use the following command:


$ tarantella config edit --PE-filter-attribute filter...

where PE-filter-attribute defines the PE filter attribute you want to configure, and filter defines the log filter. For multiple log filter definitions, use straight quotation marks to separate each filter parameter.

Each log filter has the form:

component/subcomponent/severity

The following table shows the available component names for PE logging.


Protocol Engine Component
PE Manager

pem

proxy

Execution Protocol Engine execpe

launchhelper

X Protocol Engine xpe

pem

Character Protocol Engine tpe

pem

Print Protocol Engine ppe

pem

Channel Protocol Engine cpe

pem


For subcomponent, type * to include information on all subcomponents.

You can select the following levels of severity:

Changes to the Execution, X, Character, Print, and Channel PE log filters take effect when a new PE is started.

Changes to the PE Manager log filters require an SGD server restart.



Note - Log filters can create large amounts of data. It is good practice to set as specific a filter as possible and then remove the filter after you have finished with it. See Resetting a PE Log Filter for details of how to do this.



Examples of Using PE Log Filters

The following are some examples of how to use a PE log filter.

  • To troubleshoot CDM for X and Windows applications:

    --tarantella-config-xpeconfig-logfilter "xpe/cdm/*"

  • To troubleshoot problems with X and Windows applications:

    --tarantella-config-xpeconfig-logfilter "xpe/*/*" "pem/*/*"

  • To troubleshoot application launches, you must first enable debugging in the SGD login scripts, as shown in An Application Does Not Start. Then, configure the Execution Protocol Engine log filter as follows:

    --tarantella-config-execpeconfig-logfilter "execpe/*/*"



Note - For the execpe, xpe, tpe, ppe, and cpe log filters, using the pem/* filter shows relevant PE Manager messages for the Protocol Engine.



PE Log File Destinations

PE log files have the file name extension .log. SGD formats this type of log output so that it is easy to read.

PE log file names include the name of the PE component and the process ID. For example, messages for a PE Manager running with process ID 4512 are stored to a file named pemanager4512.log.

Error messages with a severity of error, fatalerror, or warningerror are stored to a PE log file with a name that ends error.log. For example, error messages for a Character Protocol Engine running with process ID 2256 are stored to a file named cpe2256_error.log. Files such as this are used by the tarantella query errlog command, which only searches log files that have names that end error.log.

PE log filter output is directed automatically to log files in the /opt/tarantella/var/log directory on the SGD host. You cannot change the location of the log files, but you can use a symbolic link to redirect the logs to a different location.

Viewing PE Log Output

To view the PE logs, do either of the following:

  • Open the .log files in a viewer or text editor.

    On each SGD server in the array, the .log files contain messages for PEs running on that specific SGD server.

  • Use the tarantella query errorlog command to show error messages for PEs.

    This command can be used to search all PE error logs in the array.

    For example, to display X Protocol Engine error messages for all SGD servers in the array, use the following command:


    $ tarantella query errlog xpe
    

    For example, to display X Protocol Engine error messages for the SGD server boston.indigo-insurance.com, use the following command:


    $ tarantella query errlog xpe --server boston.indigo-insurance.com
    



Note - You can only use these commands to view the log output until the logs are archived. You configure archiving when you install SGD, but you can change the settings at any time by running the tarantella setup command.



Resetting a PE Log Filter

As log filters can create large amounts of data, it is good practice to reset the filter to its default configuration after you have finished with it.

The default PE log filter configuration sets a severity level of *error for all subcomponents of the PE component. The following table shows the default configuration for each log filter.


Protocol Engine Default Log Filter Configuration
PE Manager

pem/*/*error

proxy/*/*error

Execution Protocol Engine execpe/*/*error

pem/*/*error

launchhelper/*/*error

X Protocol Engine xpe/*/*error

pem/*/*error

Character Protocol Engine tpe/*/*error

pem/*/*error

Print Protocol Engine ppe/*/*error

pem/*/*error

Channel Protocol Engine cpe/*/*error

pem/*/*error


For example, to reset an X Protocol Engine log filter use the following command:


$ tarantella config edit \
--tarantella-config-xpeconfig-logfilter "xpe/*/*error" "pem/*/*error"

SGD Web Server Logging

SGD web server messages are recorded in the following logs:

Tomcat JSP Technology Container Logs

Log messages for the Tomcat JSP technology container component of the SGD web server are written to the following files in the /opt/tarantella/webserver/tomcat/6.0.18_axis1.4/logs directory on the SGD host:

  • catalina.out – This log file is rotated when full, or when the Tomcat JSP technology container is restarted, and the contents are appended to catalina.out.sav.

  • localhost_log.date.txt – This is a daily log file, where date is the date that messages were recorded.

You can read these log files with a text editor.

The Tomcat JSP technology container log files can be used to diagnose problems with the following:

  • Starting and stopping the Tomcat JSP technology container

  • Starting the AJP 1.3 Connector

  • Loading the SGD webtop web application

  • Webtop JSP software exception errors

Logging properties for the Tomcat JSP technology container are configured in the /opt/tarantella/webserver/tomcat/6.0.18_axis1.4/conf/logging.properties file. See the Tomcat documentation for details of how to configure logging for a Tomcat JSP technology container.

Apache Web Server Logs

Log messages for the Apache web server component of the SGD web server are written to the following files in the /opt/tarantella/webserver/apache/2.2.10_openssl‑0.9.8i_jk1.2.27/logs directory on the SGD host:

  • errors_log – Logs error messages for the Apache web server

  • access_log – Logs all access requests processed by the Apache web server

You can read these log files with a text editor.

The Apache web server log files can be used to diagnose problems with the following:

  • Starting and stopping the Apache web server

  • Client requests for SGD webtop pages

  • Web server authentication

See the Apache documentation for more details about these log files.

SGD Client Logging

By default, log messages for the SGD Client are stored to a file, tcc.txt, in the following locations on the client device:

Users can view the contents of this file with a text editor.

The SGD Client log file can be used to diagnose problems with the following:

Users configure the logging level for SGD Client messages by changing the Logging Level setting in their client profile. The available logging levels, arranged in increasing level of verbosity, are:

Client device information is shown on the Info -> Detailed Diagnostics page of the user’s webtop.

Administrators can use the Administration Console to view client device information for a user session. Select the user session in the User Session List table and click the View Details button to show more details.


Licensing and SGD

SGD has two licensing modes: Evaluation mode and Fully Licensed mode.


License mode Description
Evaluation mode
  • Applies when no license keys have been installed.

  • Allows you to evaluate SGD for 30 days.

  • The size of an array is limited to two SGD servers.

  • The number of users that can log in or have running applications is limited to five.

Fully Licensed mode
  • Applies when any license keys have been installed.

  • The size of an array is not limited.

  • The number of users that can log in or have running applications is limited by the installed license keys.


While you are evaluating SGD, the number of days remaining in the evaluation period is shown whenever a user logs in to SGD using a browser.

After the 30-day evaluation period, users are unable to log in to their webtop, or to start or resume applications. To continue using SGD you must obtain and install a license key.

You add license keys in the Administration Console on the Global Settings -> Licenses tab. Alternatively, you can use the tarantella license add command.

This section includes the following topics:

License Keys and Licenses

When you install a license key, it installs the licenses that unlock the software features. Licenses are one of the following types:

The following table lists the types of license available, their basis, and what they license.


License Type Basis Software Features
Base Component User Core functionality, such as the following:
  • The ability to log in.

  • The ability to authenticate users against an LDAP directory server.

  • Support for SOCKS v5 proxy servers.

  • Support for HTTP and Secure SSL proxy servers.

  • The ability to traverse firewalls.

  • The ability to use secure connections.

  • Webtops, starting applications, and managing sessions.

  • Support for arrays.

Windows Connectivity User The ability to run Windows applications.
UNIX Connectivity User The ability to run UNIX and Linux platform applications.
AS/400 Connectivity User The ability to run 5250 applications.
Mainframe Connectivity User The ability to run 3270 applications.
Advanced Load Management Array The ability to load balance application servers based on their true CPU or memory load.

User-Based Licenses

User-based licenses are enforced by the software on a concurrent user basis. A user is allocated a license as soon as they use a software component.

For example, when a user logs in to SGD, they are allocated a Base Component license. If they then run a Windows application, they are allocated a Windows Connectivity license. The license is released when they stop using the component.

A single user is never counted as using more than one of each type of license. For example, if user is logged in and is running four UNIX platform applications, the user is counted as using one Base Component license and one UNIX Connectivity license.

Note the following about user-based licenses:

  • Each guest user and anonymous user is counted as a separate user. See Using Shared Accounts for Guest Users and Anonymous User Authentication.

  • When all the Base Component licenses are allocated, additional users cannot log in to SGD.

  • If a user suspends an application, they are counted as still using a connectivity component and keep their license, even if they are not logged in to SGD.

  • If a user logs out of SGD without closing applications that are configured to be always resumable, the applications continue run, and use a connectivity component, until they time out. The default timeout period is eight days.

  • It is possible for a user to log in to SGD but not be able to run any applications. This is because there are Base Component licenses available but all the connectivity licenses are taken by users who are not logged in but have suspended application sessions.

License Administration

SGD automatically allocates and releases licenses to users as they use software components. SGD Administrators cannot manually allocate and release licenses, although they can end a user’s SGD session and their application sessions.

The SGD log files record all license usage over time. Administrators can use the tarantella license query command to display information on both current and past license usage.

Licensing Microsoft Windows Terminal Services

SGD does not include licenses for Microsoft Windows Terminal Services. If you access terminal server functionality provided by Microsoft operating system products, you need to purchase additional licenses to use such products. Consult the license agreements for the Microsoft operating system products you are using to determine which licenses you must acquire.

Terminal Services licensing is done using a CAL. A CAL is a license that allows a client to access the Windows Terminal Server. Depending on the licensing mode, a client can be either a user, or a device, or a combination of both.

Client license management for Microsoft Windows Terminal Services varies according to the client platform, as follows:

Managing CALs From the Command-Line

You can use the tarantella tscal command to manage Microsoft Windows Terminal Services CALs for non-Windows client devices, as follows:

  • To list the Terminal Services CALs currently reserved for non-Windows client devices, type the following:


    $ tarantella tscal list
    

  • To free a Terminal Services CAL for use by another non-Windows client devices, type the following:


    $ tarantella tscal free
    

  • To return all free Terminal Services CALs to the Windows License Server, type the following:


    $ tarantella tscal return --free
    


SGD Server Certificate Stores

Each SGD server has two certificate stores, a CA certificate truststore and a client certificate store.

The CA Certificate Truststore

Each SGD server has its own CA certificate truststore. This is the /opt/tarantella/bin/jre/lib/security/cacerts file.

The CA certificate truststore contains the CA certificates that the SGD server trusts.

The /opt/tarantella/etc/data/cacerts.txt file contains the X.500 Distinguished Names (DNs) and MD5 signatures of all the CA certificates that are in the CA certificates truststore when SGD is first installed. These are the CAs that SGD supports by default. To add support for additional CAs, you can import CA certificates to the truststore.

You might need to import CA certificates in the following circumstances:

The certificates that must be imported are as follows:

If the tarantella security customca command is used to install a CA certificate, or CA certificate chain, this command also imports the CA certificates into the CA certificate truststore. It only does this on the SGD server on which the command is run.

To manually import CA certificates, use the keytool application. See the JDK Tools and Utilities documentation for details on how to use the keytool application. The /opt/tarantella/var/tsp/ca.pem file on the SGD host contains the CA certificate or certificate chain.

If you need to import a CA certificate chain, import each certificate in the chain separately.

The password for the CA certificate truststore is changeit.

procedure icon  How to Import CA Certificates or Certificate Chains into the CA Certificate Truststore

  1. Log in as superuser (root) on the SGD host.

  2. Import the CA certificate.

    To import a CA certificate chain, you must import each certificate in the chain separately.

    Use the following command:


    # /opt/tarantella/bin/jre/bin/keytool -importcert \
    -keystore /opt/tarantella/bin/jre/lib/security/cacerts \
    -storepass changeit -file CA-certificate-path \
    -alias alias
    

    Use the -alias option to uniquely identify the certificate.

The Client Certificate Store

Each SGD server has its own client certificate store. This is the /opt/tarantella/var/info/certs/sslkeystore file.

The client certificate store contains the client certificates that an SGD server uses to identify itself when connecting to another server.

You create and install server client certificates with the keytool application. See the JDK Tools and Utilities documentation for details on how to use the keytool application.

You must provide a password when adding or removing certificates from the client certificate store. The password for the client certificate store is unique to each SGD server and can be found in the /opt/tarantella/var/info/key file. Use this password for both the -storepass and -keypass options.

procedure icon  How to Create a Client Certificate CSR for an SGD Server

  1. Log in as superuser (root) on the SGD host.

  2. Generate the key pair for the client certificate.


    # /opt/tarantella/bin/jre/bin/keytool -genkeypair \
    -keyalg rsa \
    -keystore /opt/tarantella/var/info/certs/sslkeystore \
    -storepass "$(cat /opt/tarantella/var/info/key)" \
    -alias alias \
    -keypass "$(cat /opt/tarantella/var/info/key)"
    

    Use the -alias option to uniquely identify the key pair.

  3. Generate a Certificate Signing Request (CSR) for the client certificate.


    # /opt/tarantella/bin/jre/bin/keytool -certreq \
    -keystore /opt/tarantella/var/info/certs/sslkeystore \
    -storepass "$(cat /opt/tarantella/var/info/key)" \
    -alias alias \
    -keypass "$(cat /opt/tarantella/var/info/key)" \
    -file CSR-path
    

    The alias must be the same as the alias used when generating the key pair. Aliases are case-insensitive.

procedure icon  How to Install a Client Certificate for an SGD Server

  1. Log in as superuser (root) on the SGD host.

  2. Install the client certificate.


    # /opt/tarantella/bin/jre/bin/keytool -importcert \
    -file certificate-path 
    -keystore /opt/tarantella/var/info/certs/sslkeystore \
    -storepass "$(cat /opt/tarantella/var/info/key)" \
    -alias alias \
    -keypass "$(cat /opt/tarantella/var/info/key)"
    

    The alias must be the same as the alias used when generating the CSR for the client certificate. Aliases are case-insensitive.


SGD Installations

This section describes the files that are included in an SGD installation. Information on backing up and restoring your SGD installation is also included.

This section includes the following topics:

About Your SGD Installation

The standard installation directory for SGD is /opt/tarantella.

During SGD installation, you have the option of specifying a different installation directory.

You can find out your installation directory from the command line, as follows:

The SGD installation directory contains the following subdirectories:

The following sections describe the contents of each of these subdirectories, and what each subdirectory is used for.

See also Backing Up and Restoring an SGD Installation.

bin Directory

The bin directory contains the scripts, binaries, and server-side Java™ technology needed to run SGD.

etc Directory

The etc directory contains configuration files that control the behavior of SGD and applications displayed through SGD. It contains the subdirectories listed in the following table.


Subdirectory Contents
etc/data The following configuration files:
  • Character application object configuration files:

    • Attribute maps (attrmap.txt)

    • Color maps (colormap.txt)

  • Printing configuration files:

    • Host name maps (hostnamemap.txt)

    • Printer driver maps (default.printerinfo.txt)

    • Printer driver to printer type mappings (printertypes.txt)

    • Printer to user-friendly name mappings (printernamemap.txt)

  • RGB color names (rgb.txt)

  • Timezone configuration files

  • Supported CA certificates (cacerts.txt)

etc/data/keymaps Keyboard map files.
etc/fonts X Window System fonts and additional fonts installed with SGD.
etc/pkg Information about installed SGD packages, for example version compatibility and dependencies.
etc/templates A complete copy of the standard files that are installed in the etc/data directory and the var/serverresources directory.

lib Directory

The lib directory contains shared libraries used by the SGD server and shared libraries that you might need when installing the SGD Client on certain platforms.

var Directory

The var directory contains the files that are used by the web server and the files that the SGD server copies to other members of the array. The var directory contains many subdirectories, and the important ones are listed in the following table.


Subdirectory Contents
var/docroot The HTML pages used by the SGD web server.
var/tsp Server SSL certificates, keys, and CA certificates.
var/ens The local repository, containing the objects in the organizational hierarchy.
var/log SGD server log files.
var/print The print queue and First In First Out (FIFO).
var/serverresources/expect SGD login scripts.
var/spool Files on their way to the print queue.

webserver Directory

The webserver directory contains the scripts, binaries, and server-side Java technology needed to run the SGD web server, web services, and the webtop. The important subdirectories are listed in the following table.


Subdirectory Contents
apache All the files needed to configure and run the SGD web server.
tomcat All the files needed to configure and run the Tomcat JSP technology and Javatrademark Servlet extension servlet container.
tomcat/6.0.18_axis1.4/webapps/axis Files needed to run SGD web services. The webtop uses web services.
tomcat/6.0.18_axis1.4/webapps/sgd Files needed to run the webtop, including the SGD Client.
tomcat/6.0.18_axis1.4/shared/lib
tomcat/6.0.18_axis1.4/shared/classes

Backing Up and Restoring an SGD Installation

This section describes how to back up an SGD installation, so that you can repair SGD in the event that a component or an entire installation becomes damaged.

Before using the procedures on this page, it is helpful if you are familiar with the layout of the SGD installation. See About Your SGD Installation.

This section includes the following topics:

procedure icon  How to Make a Full Backup of an SGD Installation

To be able to restore an SGD installation or to be able to repair some individual SGD components, you need a full backup.

While making the backup, do not run any command-line tools or use the Administration Console. It is also best if you shut down the SGD server while making the backup. However, if this is not possible, do it when the server is least loaded.

  1. Log on as superuser (root) on the SGD host.

  2. Back up the SGD log files.


    # tarantella archive
    

  3. Back up the entire SGD installation directory on each SGD server in the array.

    See About Your SGD Installation for details of the SGD installation directory.

    SGD also uses the following configuration files, which only need to be backed up if you are using them and you have modified them:

    • The /etc/ttaprinter.conf file – This file contains the lpr defaults

    • The /etc/sdace.txt and /var/ace/data files – These files contain RSA SecurID settings

    • Web server password files – If you have created these files for use with the SGD web server, and they are stored outside the SGD installation directory

Restoring a Damaged SGD Component

For the purposes of restoring a damaged installation, SGD can be divided up into the following components:

  • Binaries, scripts, and template files

  • Login scripts

  • Server configuration

  • Global configuration

  • The local repository

  • Automatic log archives

  • SGD printing

  • The SGD web server, web services, and the webtop

The following sections describe how to back up each of these components.

Binaries, Scripts, and Template Files

The binaries, scripts, and template files are only modified as part of an installation, patch, or custom engineering work. These files do not change very often.

You can restore these files from a backup or another installation, as follows:

  • The binaries are in the /opt/tarantella/bin/bin directory

  • The scripts are in the /opt/tarantella/bin/scripts directory

  • The template files are in the /opt/tarantella/etc/templates directory

Login Scripts

The Login Scripts control the interaction between SGD and the application servers, for example, by logging a user in. See Login Scripts.

How you recover login scripts depends on whether or not you are using customized login scripts.

If you are not using customized login scripts, you can restore these files from another installation, a backup, or from the /opt/tarantella/etc/templates directory.

If you are using customized login scripts, you must only restore these files from a backup.

The login scripts are in the /opt/tarantella/var/serverresources/expect directory.

Server Configuration

Server configuration covers all the properties for an SGD server that are not shared with the other SGD servers in the array, such as the server DNS name and server tuning.

As this configuration is unique to a particular SGD host, it must only be restored from a backup taken from that host.

The server-specific configuration is in the /opt/tarantella/var/serverconfig/local directory.

If you are using SGD security services, you must also restore the following:

  • /opt/tarantella/var/tsp

  • /opt/tarantella/var/info/certs

  • /opt/tarantella/var/info/key

Global Configuration

Global configuration covers all the properties that are the same for all the SGD servers in the array, for example the names of the other array members.

To restore the global configuration for an SGD server, you must only restore from a backup of the primary SGD server.

The global configuration is in the /opt/tarantella/var/serverconfig/global directory.

The Local Repository

The local repository, formerly called the Enterprise Naming Scheme (ENS) datastore, is shared across all SGD servers in the array. This is the organizational hierarchy that contains all the information about users, applications, and application servers. This information changes very often.

Restore the local repository from the backup of the primary SGD server.

The local repository is in the /opt/tarantella/var/ens directory.

Automatic Log Archives

By default, SGD archives its log files each week at 4 a.m. on Sunday, using a cron job.

If the root user’s crontab becomes corrupt, or the archiving does not take place, use the tarantella setup command to restore the default setting, or to change the time and day that the archiving takes place.

The log files are archived under the /opt/tarantella/var/log directory.

SGD Printing

When you install SGD, it configures an SGD printer queue.

If the printer queue is not present, you can restore it using either of the following methods:

The printer queue is in the /opt/tarantella/var/print directory.

SGD Web Server, Web Services, and the Webtop

The configuration of the SGD web server, SGD web services, and the webtop is unique to a particular SGD host and must only be restored from a backup taken from that host.

The configuration for the SGD web server is in the /opt/tarantella/webserver/apache/2.2.10_openssl‑0.9.8i_jk1.2.27 directory. You might also have web server password files, which can be stored in other locations.

The configuration for SGD web services is in the /opt/tarantella/webserver/tomcat/6.0.18_axis1.4 directory.

The files used for the webtop are in the /opt/tarantella/webserver/tomcat/6.0.18_axis1.4/webapps/sgd directory.

procedure icon  How to Do a Full Restore of an SGD Installation

If you are unable to restore a damaged SGD component or you are unsure about the extent of the damage to your system, you must do a full restore of your SGD installation.

To do a full restore, you must have a full backup. See How to Make a Full Backup of an SGD Installation for details of how to back up an SGD installation.

Ensure that no users are logged in to the SGD server, and that there are no application sessions, including suspended application sessions, running on the SGD server.

  1. Log on as superuser (root) on the SGD host.

  2. Stop the SGD server.

  3. Uninstall SGD.


    # tarantella uninstall --purge
    



    Note - If this fails, you might have to manually remove the SGD package. Use the rpm -e tta command on Linux platforms, and the pkgrm tta command on Solaris OS platforms.



  4. Delete the SGD installation directory.


    # rm -rf /opt/tarantella
    

  5. Reinstall SGD and any patches, if applicable.

    This installs the printer queue, rc scripts and package database.

  6. Stop the SGD server.

  7. Delete the SGD installation directory.


    # rm -rf /opt/tarantella
    

  8. Reinstate the SGD installation from the backup.



    Note - Make sure you restore from the server’s backup. Also, check that the DNS name of the host has not changed.



  9. Restart the SGD server.


Troubleshooting Arrays and Load Balancing

This section describes some typical problems when using SGD servers, and how to fix them.

The following troubleshooting topics are covered:

Troubleshooting Array Failover

To help you to diagnose and fix problems when using array failover, you can do the following:

Showing Status Information For an SGD Array

You use the tarantella status command on an SGD server to show status information for the server.

In the following example, the tarantella status command indicates a connection problem with the SGD array:


$ tarantella status
Array members (3):
 - boston.indigo-insurance.com (primary): Accepting standard connections.
 - newyork.indigo-insurance.com (secondary): Accepting standard connections.
 - detroit.indigo-insurance.com (secondary): NOT ACCEPTING CONNECTIONS.
...

If the SGD servers in the array do not agree on the array membership, tarantella status shows the array configuration as seen by every SGD server in the array. For example:


$ tarantella status
	Inconsistent array: the servers report different array membership.
...
boston.indigo-insurance.com reports 3 members as:
 - boston.indigo-insurance.com
 - newyork.indigo-insurance.com
 - detroit.indigo-insurance.com
 
newyork.indigo-insurance.com reports 3 members as:
 - newyork.indigo-insurance.com
 - boston.indigo-insurance.com
 - detroit.indigo-insurance.com
 
detroit.indigo-insurance.com reports 1 member as:
 - detroit.indigo-insurance.com

The tarantella status command indicates if the array is in a repaired state. For example:


$ tarantella status
Array members (2):
 - newyork.indigo-insurance.com (primary)
 - detroit.indigo-insurance.com (secondary)
...
This node is in a repaired array. Any alterations to array state will prevent recovery of the original array.
Use the tarantella status --originalstate command to see the original array state.

You use the --originalstate option to list the members of the array before it was repaired. For example:


$ tarantella status --originalstate
Original array members (3):
 - boston.indigo-insurance.com (primary)
 - newyork.indigo-insurance.com (secondary)
 - detroit.indigo-insurance.com (secondary)
...

Enabling Array Failover Logging

To enable logging for array failover, add the following log filters in the Log Filter field on the Global Settings -> Monitoring tab in the Administration Console:

server/failover/*:failover%%PID%%.log
server/failover/*:failover%%PID%%.jsl

See Using Log Filters to Troubleshoot Problems With an SGD Server for more information on configuring and using SGD log filters.

Troubleshooting Advanced Load Management

If you experience problems with the Least CPU Usage and Most Free Memory methods of application load balancing, you can get information from the following places to help you understand what is happening:

You can use this information to troubleshoot the following common problems:

The Load Balancing Service Is Not Working

If you think the load balancing service is not working, check the following.

Is the SGD Enhancement Module installed and running?

On Microsoft Windows applications servers, use Control Panel -> Administrative Tools -> Services to check whether the Tarantella Load Balancing Service is listed and is started.

On UNIX and Linux platform application servers, run the following command as superuser (root) to check that load balancing processes are running:


# /opt/tta_tem/bin/tem status

Is the primary SGD server running?

The load balancing service on the application server sends load information to the primary SGD server. If the primary is not available, SGD uses Fewest application sessions as the method for load balancing application servers.

Is your firewall blocking the load balancing service?

For the load balancing service to work, the firewall must allow the following connections:

  • A TCP connection on port 3579 between the SGD server and the application server.

  • A UDP connection on port 3579 between the application server and the SGD server.



Note - These connections do not need to be authenticated.



What do the log files show?

Check the log files for further information, see Troubleshooting Advanced Load Management for details.

SGD Ignores an Application Server Load Balancing Properties File

After creating a load balancing properties file for an application server, you must do a warm restart of the primary SGD server. Run the following command as superuser (root):


# tarantella restart sgd --warm

Ensure that no users are logged in to the SGD server, and that there are no application sessions, including suspended application sessions, running on the SGD server.

One of the Application Servers Is Never Picked

If one of the application servers is never picked to run applications, check the following.

Is the load balancing service running on the application server?

See The Load Balancing Service Is Not Working.

Is the application server available to run applications?

Check the application server object in the Administration Console. Ensure the Application Start check box is selected on the General tab for the application server object.

Check that the application server is up.

What do the log files show?

Check the log files for further information, see Troubleshooting Advanced Load Management for details.

One of the Application Servers Is Always Picked

If one application server is always picked to run applications regardless of its load, check the following.

Is more than one application server configured to run the application?

Check the Hosting Application Servers tab for the application object.

Are the other application servers available to run applications?

Check the application server objects in the Administration Console. Ensure the Application Start check box is selected on the General tab

Check that all the application servers are up.

Is the correct load balancing method selected?

In the Administration Console, check that either Most Free Memory or Least CPU Usage is selected as the load balancing method on the Performance tab for the application object, or on the Global Settings -> Performance tab.

Are you using server affinity?

Server affinity means that, if possible, SGD starts an application on the same application server as the last application started by the user. Server affinity is on by default, see Server Affinity.

Is the load balancing service running on the application server?

See The Load Balancing Service Is Not Working.

What do the log files show?

Check the log files for further information, see Troubleshooting Advanced Load Management for details.

Two Identical Application Servers, But One Runs More Applications Than the Other

Check that the server weighting value for the servers are the same. See Application Server’s Relative Power.

The SGD Server Log File Shows an Update Received for an Unknown ID

The SGD server log file might show an information message containing the following text:

Got an update for unknown id from machine applicationserver

This message can be ignored. It occurs only when the primary SGD server is restarted.

SGD Uses Too Much Network Bandwidth

If SGD is using a lot of network bandwidth, set the Bandwidth Limit attribute for a user profile to reduce the maximum allowable bandwidth the user can use.



Note - Reducing the available bandwidth might have implications for application usability.



In the Administration Console, go to the User Profiles tab and select the user profile object you want to configure. Go to the Performance tab and select a value from the Bandwidth Limit list.

Alternatively, use the following command:


$ tarantella object edit --name obj --bandwidth bandwidth

The following are the available bandwidths:


Administration Console Command Line
2400 bps 2400
4800 bps 4800
9600 bps 9600
14.4 Kbps 14400
19.2 Kbps 19200
28.8 Kbps 28800
33.6 Kbps 33600
38.8 Kbps 38800
57.6 Kbps 57600
64 Kbps 64000
128 Kbps 128000
256 Kbps 256000
512 Kbps 512000
768 Kbps 768000
1 Mbps 1000000
1.5 Mbps 1500000
10 Mbps 10000000
None 0



Note - None is the default. This means there is no limit on bandwidth usage.



Users Cannot Connect to an SGD Server When It Is In Firewall Traversal Mode

If users cannot connect to an SGD server when it is in firewall traversal mode, this is usually caused by starting the SGD server before the SGD web server.

In firewall traversal mode, an SGD server listens on port 443 and forwards any web connections to the SGD web server, which is configured to listen on localhost port 443 (127.0.0.1:443).

If an SGD server is started before the SGD web server, the SGD server binds to all the available interfaces and this means that the SGD server forwards any web connections to itself in an infinite loop.

One solution is to always start the SGD web server before the SGD server. If you use the tarantella start command, the SGD server and web server are always started in the correct order.

Another solution is to configure SGD so that it never binds to the localhost interface. To do this, use the following command:


 $ tarantella config edit \
--tarantella-config-server-bindaddresses-external "!127.0.0.1"



Note - On some shells you cannot use straight quotation marks, "!127.0.0.1", as the !127 might be substituted. Use single straight quotation marks instead, '!127.0.0.1'.



You can also use this command to specify exactly which interfaces you do want SGD to bind to. You do this by typing a comma-separated list of DNS names or IP addresses.

See Using Firewall Traversal for more details about running SGD in firewall traversal mode.

Users Cannot Relocate Their Sessions

When a user logs in to an SGD server without logging out of another, normally the user’s session is relocated to the new server. This is sometimes called session moving, or session grabbing.

If the clocks on all SGD servers in the array are not synchronized, user sessions might not relocate successfully.

SGD uses the time stamps on user sessions to determine which is newer. The newer user session is considered to be current. If clocks are not synchronized, the time stamps might give misleading information.

Because time synchronization is important, use Network Time Protocol (NTP) software to synchronize clocks. Alternatively, use the rdate command.

See also User Sessions and Application Sessions for more information about user sessions in SGD.