C H A P T E R  5

Client Device Support

This chapter describes how to enable support for peripherals and other client device features from applications displayed in Sun Secure Global Desktop (SGD).

This chapter includes the following topics:


Printing

This section describes how to configure printing services in SGD and includes the following topics:

Overview of SGD Printing

SGD supports two types of printing: PDF printing and Printer-Direct printing.

With PDF printing, users print from an application using an SGD PDF printer. The print job must be in PostScripttrademark format. The PostScript print job is sent from the application server to an SGD server, where it is converted into a Portable Document Format (PDF) file. The SGD server then sends the PDF file to a PDF viewer on the user’s client device, where the file can be viewed, saved, and printed.

With Printer-Direct printing, users print from an application to a printer attached to their client device. SGD does this by cooperating with the lp or lpr printing system on the SGD host and the native printing system on the application server. The print job is sent from the application server to an SGD server. The SGD server then sends the print job to the SGD Client, which sends it to the user’s client printer. If the format of the print job used by the application server is different to the format needed by the client printer, SGD converts the print job before sending it to the SGD Client.

PDF printing is usually more reliable and produces better results than Printer-Direct printing.

SGD has two PDF printers: Universal PDF Printer and Universal PDF Viewer.

On Microsoft Windows client devices, the Universal PDF Printer displays the print job as a PDF file in the Adobe® Reader, which then prints the PDF file to the user’s default printer. The Universal PDF Viewer displays the print job as a PDF file in the Adobe Reader, which the user can then decide whether to print or save.

On UNIX®, Linux, and Mac OS X platform client devices, there is no difference between the Universal PDF Printer and Universal PDF Viewer, as the print job is always displayed as a PDF file in a PDF viewer. The user can then decide whether to print or save the PDF file.

SGD uses distributed printing. Print jobs are sent to the SGD server hosting the user’s application session. This means that a user’s print jobs are distributed across the array, and there are no bottlenecks or single points of failure.

SGD supports printer-direct printing to PostScript, Printer Command Language (PCL), and text‐only printers attached to the user’s client device. The SGD tta_print_converter script performs any conversion needed to format print jobs correctly for the client printer. To convert from Postscript to PCL, Ghostscript must be installed on the SGD server.

Setting Up Printing

Setting up printing involves the following configuration steps:

  1. Configure application server for printing.

    The required configuration for the application server depends on the application server platform.

    See Configuring Microsoft Windows Application Servers for Printing.

    See Configuring UNIX and Linux Platform Application Servers for Printing.

  2. Configure the SGD servers for printing.

    See Configuring an SGD Server for Printing.

  3. Configure printing to client devices.

    The required configuration depends on the client device platform.

    See Configuring Printing to Microsoft Windows Client Devices.

    See Configuring Printing to UNIX, Linux, and Mac OS X Platform Client Devices.

Configuring Microsoft Windows Application Servers for Printing

The configuration required to print from applications running on a Microsoft Windows application server depends on whether or not the Microsoft Remote Desktop Protocol (RDP) protocol is used to connect to the application server. See the following:

Configuring Printing for Microsoft RDP

If the connection method used for the Windows application is Microsoft RDP, SGD automatically creates printer queues in the Windows application session if the application server supports Microsoft RDP version 5.0 or later. This applies to Microsoft Windows 2000 Server and later application servers.



Note - The version of Microsoft RDP supported by Windows NT 4 is not version 5.2 or later. To configure printing from NT 4, see Configuring Other Microsoft Windows Application Servers for Printing.



When a user starts or resumes a Windows application that uses the Microsoft RDP Windows Protocol, the SGD Client sends information about the client’s printers to SGD. SGD supplies this information to the application server and the application server then creates, or maps, the printers in the Windows Terminal Services session. The user sees the printers that are attached to the client device and also the printers that are attached directly to the application server.

To be able to create a client printer in the Microsoft Windows application session, the following must be true:

  • Printer mapping must be enabled on the application server, see Configuring Microsoft Windows Terminal Services for Use With SGD for details.

  • The SGD Client must determine the name of the printer driver for the client printer and send it to application server.

  • The printer driver for the client printer must be installed on the application server.

The printer drivers that must be installed on the application server are as follows:

In a Windows Terminal Services session, the names of the client printers are displayed in the application server’s Printers folder, as “printer-name (from Sun SGD) in session number”. For example, HP LaserJet 8000 Series PS (from Sun SGD) in session 1.

SGD Administrators can control the SGD printers that are available in Windows Terminal Services sessions. See Configuring the Printers Available in Windows Terminal Services Sessions.

Configuring the Printers Available in Windows Terminal Services Sessions

SGD enables Administrators to control the printers that are available in Windows Terminal Services sessions. You can configure the printers, as follows:

  • Globally. In the Administration Console, go to the Global Settings -> Printing tab.

  • Individually. In the Administration Console, go to the Printing tab for an organization, an organizational unit, a user profile, or a Windows application object.

    If you configure an organization or organizational unit object, this affects all the users in that organization or organizational unit.

    If you configure a Windows application object, this overrides the printing configuration for organization, organizational unit, or user profile objects. The order of precedence for printing configuration is: Windows application -> user profile -> organizational unit -> organization.

You can set the following attributes on the Printing tab.


TABLE 5-1   Attributes Used to Configure Printing From Terminal Services Sessions
Attribute Description
Client Printing Controls the client printers users can print to, either all client printers, the default client printer, or no client printers.

By default, users can print to all their client printers.

Universal PDF Printer Enables the Universal PDF Printer printer.
Make Universal PDF Printer the Default Sets the Universal PDF Printer printer as the client device’s default printer for Windows applications.
Universal PDF Viewer Enables the Universal PDF Viewer printer.
Make Universal PDF Viewer the Default Sets the Universal PDF Viewer printer as the client device’s default printer for Windows applications.
Postscript Printer Driver The name of the PostScript printer driver to use for PDF printing.



Note - Any configuration changes you make on the Printing tab only take effect for new user sessions.



If you make a PDF printer the default printer for Windows applications and SGD is configured to only allow users to print to their default printer, users see two printers in their Windows application session. The user’s default client printer and the PDF printer are shown.

To use PDF printing, you must install the PostScript printer drivers you want to use for PDF printing on the application server. Make sure the printer drivers have sufficient features for your users. By default, SGD is configured to use the HP Color LaserJet 8500 PS printer driver. The printer driver name entered in the Postscript Printer Driver field on the Printing tab must match the name of the printer driver installed on the application server exactly. Pay particular attention to the use of capitals and spaces. The /opt/tarantella/etc/data/default.printerinfo.txt file contains all the common printer driver names, ordered by manufacturer. To avoid errors, copy and paste the driver name from this file.



Note - If a PDF viewer is not configured on the client device, the PDF printers are not available in the Windows application session, even if a PDF printer is enabled.



Configuring Other Microsoft Windows Application Servers for Printing

To print from an Microsoft Windows application that is configured to use either the Citrix Independent Computing Architecture (ICA®) protocol, or an earlier version of the Microsoft RDP protocol, you must configure a Line Printer Remote (LPR)-compatible Transmission Control Protocol/Internet Protocol (TCP/IP) printer on the application server. Configure the printer to send print jobs to the primary SGD server in the array. Consult your system documentation for details of how to configure printers.

Note the following limitations:

  • PDF printing is not supported.

  • No multiple printer support. You can only print to the client device’s default printer. It is not possible for users to select a printer. If a user needs to print to a different printer, they have to log out of SGD, change their default printer, and then log in again.

  • Print jobs might be deleted. When a print job is transferred from the application server to an SGD server, the user’s SGD name is needed to identify which client device to send the print job to. With some versions of Microsoft Windows, there is no direct way to associate print jobs with SGD users. If SGD cannot identify which user has printed a particular job, the print job is deleted. This might happen, for example, if two users log in to the application server with the same name.

  • Distributed printing is not available. All print jobs are directed through the primary server in an SGD array.

Configuring UNIX and Linux Platform Application Servers for Printing

To use PDF printing from a UNIX or Linux platform application server, you must install at least one SGD printer queue on the application server. You do not have to install printer queues for the Universal PDF Printer and Universal PDF Viewer. However, if a UNIX or Linux platform application you are using does not allow you to configure printer arguments, or does not allow you to specify the Universal PDF Printer and Universal PDF Viewer because their names contain spaces, you must install an additional printer queue called tta_pdfprinter and print to that queue.

To use Printer-Direct printing from a UNIX or Linux platform application server, you must install SGD printer queues as follows:

You configure printer queues with the SGD printer queue installation script. See How to Install an SGD Printer Queue on a UNIX or Linux Platform Application Server.

The SGD printer queue installation scripts installs replacement lp or lpr scripts. These are used instead of the standard scripts, to ensure that print jobs contain enough information for SGD to be able to identify the user that printed them. See Printing With the SGD lp and lpr Scripts for details.

procedure icon  How to Install an SGD Printer Queue on a UNIX or Linux Platform Application Server

If the application server is also an SGD server, a printer queue is installed automatically when you install SGD.

  1. Copy the /opt/tarantella/bin/scripts/prtinstall.en.sh script from an SGD server to a temporary directory on the application server.

  2. Log in to the application server as superuser (root).

  3. Change to the temporary directory.

  4. Run the script to install the printer queue.

    See The SGD Printer Queue Installation Script for details of all the command options for the SGD printer queue installation script.

    • If the array consists of a single SGD server, use the following command:


      # sh prtinstall.en.sh
      

      When prompted, type the full Domain Name System (DNS) name of the SGD server.

    • If the array contains more than one SGD server, create a printer queue for each SGD server in the array. Use the following command:


      # sh prtinstall.en.sh --ttahost DNS-name --appprinter name
      

      The DNS-name is the full DNS name of an SGD server. The name of each printer queue, as specified by the --appprinter argument, can be anything you like but it must be unique.

    If you use the Common UNIX Printing System (CUPS), you might have to use the --cups option with prtinstall.en.sh, to indicate that you are using CUPS. You might also have to reconfigure CUPS. See Configuring Printing for CUPS.

The SGD Printer Queue Installation Script

The SGD printer queue installation script, prtinstall.en.sh, installs an SGD printer queue on a UNIX or Linux platform application server. It also installs the SGD replacement lp or lpr scripts.

The prtinstall.en.sh script is located in the /opt/tarantella/bin/scripts directory on the SGD server.

You must be superuser (root) to run this script.

The syntax for the script is as follows:

sh prtinstall.en.sh [--ttahost SGD_hostname]
                    [--ttaprinter printer_name]
                    [--appprinter printer_name]
                    [--uninstall [printer_name]]
                    [--cups y | n | auto]
                    [--cupsconf filename]
                    [--cupscontrol filename]
                    [--gsbindir gs_bin_dir]
                    [--append]
                    [--help]

The following table describes the available options for the script.


Option Description
--ttahost SGD_hostname Fully qualified DNS name of an SGD server
--ttaprinter printer_name Use this option to specify a name for the printer queue. Use this if the SGD server is also used as an application server. If you do not use this option, the printer is created with the default name of tta_printer.
--appprinter printer_name Use this option to specify a name for the printer queue on a UNIX or Linux platform application server. If you do not use this option, the printer queue is created with the default name of tta_printer.
--uninstall [printer_name] Uninstalls an SGD printer queue. If you do not specify a printer queue, you are prompted for one.
--cups y | n | auto Indicates that you are using CUPS.

If you do not use this option, a default of auto is assumed and this means SGD tries to detect whether CUPS is being used. If CUPS is incorrectly detected, use this option to tell SGD whether CUPS is being used (y) or not (n).

--cupsconf filename Specifies the path to the CUPS configuration file.

If you do not use this option, the CUPS configuration file is assumed to be /etc/cups/cupsd.conf.

--cupscontrol filename Specifies the path to the CUPS startup script.

If you do not use this option, the CUPS startup script is assumed to be /etc/init.d/cups.

--gsbindir gs_bin_dir Use this option to specify the directory where Ghostscript is installed.

Use this option if Ghostscript is not installed in one of the default locations, or to specify the version of Ghostscript to use, if more than one version is installed.

Only use this option if you are running the printer queue installation script on the SGD host. See Checking the Ghostscript Installation on the SGD Host for details.

--append Installs an additional printer queue rather than replacing the existing printer queue(s).
--help Shows the list of prtinstall.en.sh script options.

The following example installs an SGD printer called tta_london on an application server.


# sh prtinstall.en.sh --appprinter tta_london

Configuring Printing for CUPS

SGD printing only works with CUPS version 1.1.19 or later. The following configuration changes might be needed to enable printing with CUPS:

  • CUPS LPD compatibility mode must be enabled for any LPD clients.

    If you have any Line Printer Daemon (LPD) clients on your application server, you must enable the CUPS LPD compatibility mode so that CUPS can accept remote print jobs from LPD clients. The CUPS Software Administrators Manual explains how you enable LPD compatibility mode.

  • CUPS raw printing must be enabled.

    On the host where SGD is installed, enable raw printing in CUPS, by editing the /etc/cups/mime.convs and/etc/cups/mime.types files. These files contain comments explaining how to do this. Search for comments containing the word “raw”.



Note - After making changes to your CUPS configuration, you might have to restart the CUPS daemon.



To use CUPS for printing, you must use the /opt/tarantella/bin/lp script.

Printing With the SGD lp and lpr Scripts

The SGD printer queue installation script, prtinstall.en.sh, installs the SGD lp or lpr replacement scripts. Users must use these replacement scripts when they print from a UNIX or Linux platform application server. The replacement scripts ensure that print jobs contain enough information for SGD to be able to identify the user that printed them.

The SGD login scripts set the user’s PATH to ensure that the replacement scripts take precedence over the system scripts. However, if the application uses a full path name, for example /usr/bin/lp, or modifies PATH itself, you must reconfigure the application to use /opt/tarantella/bin/lp or /opt/tarantella/bin/lpr.

Users print with the replacement scripts as follows:


$ lp -d printer file


$ lpr -P printer file

If the -d or -P argument is omitted, the output goes to the client’s default printer. How you specify the printer depends on the client device. See Configuring Printing to Microsoft Windows Client Devices and Configuring Printing to UNIX, Linux, and Mac OS X Platform Client Devices for details.

Configuring an SGD Server for Printing

Configuring an SGD server for printing involves the following configuration steps:

Checking the Ghostscript Installation on the SGD Host

SGD uses Ghostscript to convert print jobs into PDF files. To use PDF printing, Ghostscript version 6.52 or later must be installed on the SGD host. Your Ghostscript distribution must include the ps2pdf program.

With Printer-Direct printing, the tta_print_converter script uses Ghostscript to convert print jobs from PostScript to PCL format. For best results, download and install the additional fonts.

Ghostscript is not included with the SGD software.

When you install SGD, it automatically detects Ghostscript if it is installed in one of the following locations:

  • /usr/local/bin

  • /usr/bin

  • /usr/sfw/bin

  • /opt/sfw/bin

  • /bin

  • /usr/sbin

  • /sbin

  • /usr/lbin

If Ghostscript is installed in a different location, run the SGD printer queue installation script on the SGD host. Use the --gsbindir option of the script to configure the location of Ghostscript. See The SGD Printer Queue Installation Script for more details.

If more than one version of Ghostscript is installed, run the SGD printer queue installation script with the --gsbindir option, to tell SGD which version to use.

If Ghostscript is not installed on the SGD host, or your Ghostscript distribution does not include the ps2pdf program, install Ghostscript and then run the SGD printer queue installation script.

Using the gstest Script to Test a Ghostscript Installation

You can use the gstest script to test the Ghostscript installation on an SGD host. This script is run by default when you install SGD.

The gstest script checks for errors in the Ghostscript installation and uses ps2pdf to generate a test PDF file. Script output is reported on-screen, and is also written to the /opt/tarantella/var/log/print.log file.

You run gstest as follows:


# /opt/tarantella/bin/scripts/gstest

Using gstest in this way performs a basic test of the font installation on the SGD host and generates a fonts test file, /opt/tarantella/var/info/sample.pdf. If Ghostscript fonts are installed correctly, the sample.pdf file contains three lines, each rendered in a different font. The fonts used are listed in the /opt/tarantella/var/log/print.log file.

Alternatively, you can specify an input file and output file to use with gstest. For example:


# cd /opt/tarantella/bin/scripts
# gstest /tmp/myPostScriptFile.ps /home/indigojones/myPDFFile.pdf

If you do not specify an output file, gstest creates an output PDF file at /tmp/sgd_sample.pdf.



Note - If you specify your own input file, gstest does not generate the fonts test PDF file, /opt/tarantella/var/info/sample.pdf.



Configuring the SGD Host to Accept Remote Print Requests

Print jobs are sent from the application server to an SGD server, and then from the SGD server to the client device. To be able to direct print jobs from an application server to a client device, the SGD host must be configured to accept remote print requests. How you do this varies for each platform. Check your System Administration documentation for information about this.

For example, if you are using lpd on Linux systems, you must add an entry in the /etc/hosts.equiv or /etc/hosts.lpd file, if available, for each application server that might send a print request. After making these changes, remember to restart the lpd daemon.



Note - For Windows applications that use the Citrix ICA Windows protocol, the entry in /etc/hosts.equiv is for the UNIX platform server running the ICA client.



Configuring SGD Print Job Conversion

With Printer-Direct printing, print jobs are sent from an application server to an SGD server. The SGD server then sends the print job to the client device, which sends it to the user’s printer. When print jobs arrive at the SGD server, they might need to be converted to a format suitable for the client printer.



Note - Print jobs from Windows application sessions that use the Microsoft RDP protocol are never converted, because they are assumed to be in the correct format.



To decide whether a print job needs to be converted, the SGD server checks a printer type configuration file to see whether the format used by the client printer matches the format used by the application server. If the format matches, the print job is forwarded to the client device printer without any conversion. If the formats do not match, the SGD server converts the print job to the right format using the tta_print_converter script.

To ensure that print jobs are formatted correctly, you might have to edit a printer type configuration file and the tta_print_converter script. This is described in the following sections.



caution icon

Caution - Only edit these files if you have to use Printer-Direct printing and need to resolve issues with print job formats. In most cases, PDF printing provides a better solution for issues with print job formats.



Printer Type Configuration Files

SGD uses the following configuration files to determine the printer type:

You can edit these files if you want to support particular printers, or to add new types of printer.



Note - If you add a new printer type, you might also have to edit the tta_print_converter script.



If there is insufficient detail or inaccurate mappings in these files, SGD might convert print jobs unnecessarily, or not at all.

The tta_print_converter Script

The tta_print_converter script converts print jobs from the format used by the application server to the format required by the client device, as determined by the printer type. By default, the script recognizes PostScript and non-PostScript formats. To convert print jobs from PostScript to PCL, Ghostscript must be installed on the SGD host. See Checking the Ghostscript Installation on the SGD Host for more information about installing and configuring Ghostscript for SGD printing.

You can edit the tta_print_converter script to recognize and convert between different print job formats, or to add support for a new printer type.



Note - You must log on as superuser (root) to edit the script.



The tta_print_converter script is in the /opt/tarantella/bin/scripts directory. The script includes comments, to help you to customize it.

The shell function GetDataType determines the print job format from the first 128 bytes of the print job. The data is Uniform Resource Locator (URL)-encoded, for example, the % character is encoded as %25.

The client printer type is passed to this script in upper case, for example, POSTSCRIPT or MYNEWTYPE.

If you experience problems printing to a PCL printer, the tta_print_converter script contains some code which has been commented out. You can use this code to see if this solves the problem.

Configuring Printing to Microsoft Windows Client Devices

The configuration required for printing to Microsoft Windows client devices depends on whether you are using PDF printing or Printer-Direct printing, as described in the following sections.

PDF Printing

To be able to use PDF printing, the Adobe Reader version 4.0 or later must be installed on the client device.

From a Microsoft Windows application, you print in the normal way, and select either the Universal PDF Printer or the Universal PDF Viewer in the application’s Print dialog.

From an application running on a UNIX or Linux platform application server, you print in the normal way, using the SGD replacement lp or lpr scripts. You select a PDF printer as part of the print command, for example:


$ /opt/tarantella/bin/lp -d "Universal PDF Printer" filename


$ /opt/tarantella/bin/lpr -P "Universal PDF Viewer" filename



Note - The filename must be a PostScript file, so the application must be able to output PostScript.



When users print, the PDF file is displayed in the Adobe Reader. If the Universal PDF Printer is selected, the PDF file is printed automatically to the user’s default printer. The Adobe Reader runs minimized and does not exit when the print job has finished. If the Universal PDF Viewer is selected, the PDF file is displayed in the Adobe Reader window. The user can then decide whether to print or save the file.

On UNIX, Linux, and Mac OS X platform client devices, the PDF file is displayed either in the default PDF viewer or in the PDF viewer configured in the client profile. The user can then decide whether to print or save the PDF file. There is no difference between the Universal PDF Printer and the Universal PDF Viewer, as the print job is always displayed in a PDF viewer.

Printer-Direct Printing

This section describe the configuration that might be needed when using Printer-Direct printing to print to Microsoft Windows client devices and includes the following topics:

Printer Driver Mapping

When printing from a Microsoft Windows application, the large number and variety of client printers available can cause problems. The majority of the problems are caused by not having the correct printer drivers installed on the application server. One solution is to use PDF printing. Another solution, for Windows client devices only, is to use printer driver mapping.

Printer driver mapping enables you to map one printer driver name to another. You do this by editing the [Previous Names] section of the /opt/tarantella/etc/data/default.printerinfo.txt file.

The following is an example of an entry in a default.printerinfo.txt file:

[Previous Names]
"HP LaserJet 5" = "my HP driver", "my other HP driver"

This means that if users have client printers that use either the "my HP driver" or "my other HP driver" printer driver, SGD uses the "HP LaserJet 5" printer driver when creating the printer.

You can also use wild-card characters, such as * and ?, on the right hand side of the = sign. Use * to mean any string of characters, including an empty string and ? to mean any single character. This is useful, for example, to create generic printer mappings where you have a wide variety of client devices.

For example, if the file contains the following entry:

[Previous Names]
"HP LaserJet 5" = "hp*laserjet 5*"

All printer driver names like "HP LaserJet 5", "HP LaserJet 5M", and "HP Color LaserJet 5" are mapped to the printer driver "HP LaserJet 5".

The default.printerinfo.txt file contains more detailed instructions on how to create the mappings.

The Printer Types Configuration File

For Microsoft Windows client devices, SGD uses the /opt/tarantella/etc/data/printertypes.txt file to determine whether to convert a print job from one format to another before sending it to the client device. The printertypes.txt file maps printer drivers, for example, pscript.dll, to printer types, for example PostScript.



Note - Print jobs from Windows application sessions that use the Microsoft RDP protocol are never converted, because they are assumed to be in the correct format.



The printertypes.txt file includes comments to help you to customize it. By default, the file includes mappings for PostScript, PCL, and text-only printers. You must log on as superuser (root) to edit this file.



Note - The printertypes.txt file used for Windows clients also contains entries for UNIX platform and Apple Macintosh clients. This is used only as a fallback. For UNIX or Linux platforms, it maps UNIX types to printer types. For Apple Macintosh, it maps printer names to printer types.



To find out the name of the printer driver used by a client device, print a test page and check the Driver Name field.

To add support for a new printer type, add lines following the same pattern. For example:

MyNewType=mydriver.drv

For example, a client device, cairo, runs Windows 2000 and its default printer is PCL. The printer driver used is unidrv.dll. The [Windows*] section in printertypes.txt has the following format:

[Windows*]
PostScript=pscript5.dll;pscript.dll
PCL=rasdd.dll
PostScript=*

As there is no specific match for unidrv.dll, the final entry applies: PostScript. This means that when the user prints, print jobs are incorrectly converted to PostScript before being sent to cairo.

To fix this, edit printertypes.txt as root and add a specific match for unidrv.dll as follows:

PCL=rasdd.dll;unidrv.dll

Following this change, SGD correctly identifies the printer configured on cairo, and print jobs are converted to PCL for that client device.

Printing From a UNIX or Linux Platform Application Server

When printing from a UNIX or Linux platform application server to a Microsoft Windows client device, users can specify the printer they print to by using any of the following:

  • The Universal Naming Convention (UNC) name of a network printer accessible to the client, for example:


    $ lp -d '\\\\PRTSERVER\\HPLJ5' filename
    

  • A “friendly” name, for example:


    $ lpr -P label-printer filename
    

  • A port on the client, for example:


    $ lpr -P LPT1: filename
    

To use a UNC name, you must enclose the printer name in quotes and escape every backslash with an extra backslash, as shown in the previous example. As different shells process backslashes differently, you might need to experiment with the number of backslashes. You can also use underscores instead of backslashes, for example:


$ lp -d __PRTSERVER_HPLJ5 filename



Note - Using underscores only works if the first two characters of the printer name are underscores.



You can avoid problems with UNC names by using a “friendly” name. You configure “friendly” names in the /opt/tarantella/etc/data/printernamemap.txt file. The entries in this file map “friendly” names to UNC names, for example:


"label-printer"="\\PRTSERVER\HPLJ5"



Note - You do not have to escape any backslashes.



Configuring Printing to UNIX, Linux, and Mac OS X Platform Client Devices

The configuration required for printing to UNIX, Linux, and Mac OS X platform client devices depends on whether you are using PDF printing or Printer-Direct printing, as described in the following sections.

PDF Printing

To be able to use PDF printing, a PDF viewer must be installed on the client device. SGD supports the following PDF viewers by default.


Client Platform Default PDF Viewer
Solaris OS on SPARC platforms Adobe Reader (acroread)

GNOME PDF Viewer (gpdf)

Solaris OS on x86 platforms GNOME PDF Viewer (gpdf)
Linux GNOME PDF Viewer (gpdf)

X PDF Reader (xpdf)

Mac OS X Preview App (/Applications/Preview.app)



Note - The Adobe Reader PDF viewer must support the -openInNewWindow command option. The Preview App PDF viewer must support the open -a command option.



To be able to use a default PDF viewer, the application must be on the user’s PATH.

If an alternative PDF viewer is preferred, the command for the alternative viewer application can be configured in the user’s client profile. In the profile you enter either the command or the full path to the command, depending on whether the application is on the user’s PATH. See Client Profile Settings for details.

From a Microsoft Windows application, you print in the normal way, and select either the Universal PDF Printer or the Universal PDF Viewer in the application’s Print dialog.

From an application running on a UNIX or Linux platform application server, you print in the normal way, using the SGD replacement lp or lpr scripts. You select a PDF printer as part of the print command, for example:


$ /opt/tarantella/bin/lp -d "Universal PDF Printer" filename


$ /opt/tarantella/bin/lpr -P "Universal PDF Viewer" filename



Note - The filename must be a PostScript file, so the application must be able to output PostScript.



The PDF file is displayed either in the default PDF viewer or in the PDF viewer configured in the client profile. The user can then decide whether to print or save the PDF file. There is no difference between the Universal PDF Printer and the Universal PDF Viewer, as the print job is always displayed in a PDF viewer.

Printer-Direct Printing

To use Printer-Direct printing to print to printers attached to UNIX, Linux, or Mac OS X platform client devices, the client printers must be defined in one of the following printer configuration files:

  • Global printer configuration file /opt/tarantella/etc/data/default.printerinfo.txt.

    This file set the defaults for all users printing through that SGD server. As this file is not replicated across the array, you have to manually copy it to the other SGD servers.

  • User-specific printer configuration file$HOME/.tarantella/printerinfo.txt.

    The user-specific printer configuration file is optional and has to be manually created on client devices. Users can create their own file or you can use the global configuration file as a template and distribute it to users. This file contains the settings for an individual user regardless of the SGD server they print through. The settings in this file take precedence over the settings in the global configuration file.

The format of the global and user-specific printer configuration file is the same:

[UNIX]
"printer-name" = "windows-driver" printer-type
"printer-name" = "windows-driver" printer-type
...

printer-name is the name of the printer as it is known to the lp or lpr system on the client. The printer name must be enclosed in straight quotation marks (") and be followed by an Equal (=) sign. This is the name that users can specify when printing from a UNIX or Linux platform application server. It is also the name that displays in the Print dialog when users print from a Microsoft Windows application server.

windows-driver is the name of the printer driver to use when printing from a Microsoft Windows application server. The printer driver name must be enclosed in double quotes. The name of the printer driver must match the name of the printer driver installed on the Windows application server exactly. Pay particular attention to the use of capitals and spaces. The default.printerinfo.txt file contains all the common printer driver names ordered by manufacturer. To avoid errors, copy and paste the driver name from this file.

printer-type is the format to be used for the print job. The values can be PostScript, PCL or Text. This information is optional, but if it is missing, PostScript is used by default. This information is used to determine whether SGD needs to convert the print job from the format used by the application server to the format needed by the client printer. See also Configuring SGD Print Job Conversion.

The first printer listed in the [UNIX] section is the client’s default printer.

When SGD is first installed, the default.printerinfo.txt file contains the following entry:

[UNIX]
"_Default" = "QMS 1060 Print System" PostScript

With this configuration, when users print from a Windows application server, they see a printer called _Default (from Sun SGD) Session number. This printer prints to the default printer on the client using a basic PostScript printer driver, “QMS 1060 Print System”.



Note - This means that a printer is available in the Windows application, even if there is no printer connected to the client device.



For example, if an SGD user’s $HOME/.tarantella/printerinfo.txt file contains the following entries:

[UNIX]
“drafts” = “HP Diskette 970Cxi” PCL
“salespersons” = “HP Lacerate 5/5M” PostScript

When the user prints from a Microsoft Windows application server to a UNIX platform client device, the following printers are available:

  • drafts/Sun SGD/Session number

  • salespersons/Sun SGD/Session number

The user’s default printer is drafts/Sun SGD/Session number, which in this example has been defined as a PCL printer.

Managing Printing

This section describes the print job management features of SGD and includes the following topics:

The tarantella print Command

SGD Administrators control printing services with the tarantella print command. This command enables you to do the following:

  • List spooled print jobs and identify the SGD users they belong to. You can use this to check that print jobs from the application server printing system have reached the SGD print queue.

  • Remove print jobs from the SGD print queue.

  • Pause and restart SGD printing services.

  • Move print jobs from one SGD server to another.

The syntax for the tarantella print command is as follows:

tarantella print start | stop | status | pause | resume | list | cancel | move

The following table shows the available subcommands for tarantella print.


Subcommand Description
cancel Cancels print jobs
list Lists print jobs
move Moves queued print jobs from one SGD server to another
pause Pauses printing temporarily
resume Resumes printing
start Starts printing services for the array
status Displays information about printing services
stop Stops printing services

Setting a Time Limit for Print Jobs

SGD Administrators can set a time limit on how long a print job can remain on an SGD server before it is deleted. This is useful if you have to manage a high volume of printing.

To specify the number of hours that print jobs remain on the server, use the following command:


$ tarantella config edit \
--tarantella-config-array-printjoblifetime hours

To return SGD to its default behavior, so that print jobs remain on the server indefinitely, use the following command:


$ tarantella config edit \
--tarantella-config-array-printjoblifetime 0

User Management of Print Jobs

Users can manage their own print jobs from the Printing area on the webtop, as shown in FIGURE 5-1.

FIGURE 5-1   Printing Area on the SGD Webtop

Screenshot Showing the Printing Area on the
SGD Webtop


The Printing area shows the number of jobs currently in the print queue and the controls for managing print jobs.

When documents are printing, the webtop tells a user how many print jobs they have in the queue. Users can click Cancel All to delete all pending print jobs.

Users can also click Pause to temporarily stop printing. When printing is paused, any print jobs that are pending are held in a queue until the user either cancels them or resumes printing. Click Resume to start printing again. The printer icon changes to show you when printing is paused.

To manage print jobs individually, click List all jobs. The webtop displays a list of all the print jobs the user has in the queue, along with information about the job, for example the number of copies and the selected printer.

If you pause printing, click the Resume button to print just that one print job.

To cancel a print job, click the Cancel button.

When printing from a Microsoft Windows application server using Microsoft RDP, or a UNIX or Linux platform application server, users can choose which printer they print to. If the user does not select a printer, the output goes to their default printer. For all other application servers, the output always goes to the client device’s default printer.

Users can see which printer is their default printer by pointing with the mouse at the printer icon on their webtop. A popup displays the name of the default printer.

If a user wants to change their default printer, they must log out of SGD, change the default printer and then log in to again.

Users Cannot Print From Applications Displayed Through SGD

Use the following checklists to diagnose and fix the problem:

If this does not resolve the problem, follow the steps in Tracing a Print Job.

Client Devices Checklist

Use the following client device troubleshooting steps to diagnose printing problems in SGD.

Does SGD Support Printing for the Client Device or Printer Type?

Check the Printing Area on the webtop. Does the printer icon contain a red cross and is the message “No Client Printer Available” displayed? If so, this means that SGD does not support printing for this client device or printer type, or that there was an error creating client printers.

Is Printing Paused on the Client Device?

Make sure that the user has not paused printing. Check the Printer Paused icon is not displayed.

Use the tarantella webtopsession list command to see whether the user has paused printing.

Is the Printer Configured Correctly?

Make sure that the printer is correctly configured, for example by printing a web page to the printer from a web browser on the client device. Depending on the application server, some print jobs can only go to the client device’s default printer.

If printing to a UNIX, Linux, or Mac OS X platform client device, check that you have configured printing for these client types. See Configuring Printing to UNIX, Linux, and Mac OS X Platform Client Devices.

For PDF Printing, is the PDF Viewer Installed on the Client?

To be able to use PDF printing in SGD, a PDF viewer must be installed on the client device.

Check that the supported viewer, or the user’s preferred viewer, is installed on the client and that the application is executable.

On UNIX, Linux, or Mac OS X system client devices, check that the user has read and write access to the /tmp directory.

If the PDF viewer is Adobe Reader (acroread), check that the viewer supports the -openInNewWindow command option. If the PDF viewer is Preview app (/Applications/preview.app), check that the viewer supports the open -a command option.

If a PDF viewer is not installed or accessible, the SGD PDF printers are available to the user.

For PDF Printing From a UNIX or Linux Platform Application Server, is the Print Job in the Right Format?

If the user’s PDF viewer starts, but they receive a file format error, check that the format of the file being printed on a UNIX or Linux platform application server is PostScript.

Does the User Have the Necessary Registry Permissions?

On Microsoft Windows client devices, users must have write access to the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\RNG\Seed registry key and read access to the rest of the registry.

This access is required by several of the Windows application programming interfaces (APIs) for printing.

Application Server Checklist

Use the following application server troubleshooting steps to diagnose printing problems in SGD.

Is a Printer Configured on the Application Server?

Before users can print, you might need to configure a SGD printer on your application server. See the following:

Is the Printer Created in the Windows Application Session?

If the user is trying to print from a Microsoft Windows application server, accessed using Windows Terminal Services, then the user’s printers are configured automatically. See Configuring Printing for Microsoft RDP. If not, check the System event log on the application server for the following errors:

  • Event ID: 1111 Description: Driver drivername required for printer printertype is unknown. Contact the administrator to install the driver before you log in again.

  • Event ID: 1105 Description: Printer security information for the printername / clientcomputername /Session number could not be set

  • Event ID: 1106 Description: The printer could not be installed.

These errors indicate that the printer driver for the client printer might not be supported by the application server. Either install the printer driver on the application server, or see Printer Driver Mapping for details of how to support other printer drivers, including using wildcards to support a wide range of printer driver names.

It is also worth checking that the name of the printer driver in /opt/tarantella/etc/data/default.printerinfo.txt, or the user’s $HOME/.tarantella/printerinfo.txt, matches the name of the driver on the application server.

If this does not resolve the problem, see Microsoft Knowledge Base article 239088 for more details.

Is the Application Printing to the Correct Printer?

The application must print to the printer queue you have configured. On UNIX or Linux platform application servers, the prtinstall.en.sh script creates a printer queue named tta_printer by default.

On UNIX or Linux platform application servers, the application must print using the replacement lp or lpr scripts installed by prtinstall.en.sh. The SGD login scripts set PATH to ensure that the replacement scripts take precedence over the system scripts. If the application uses a full path name, for example /usr/bin/lp, or modifies PATH itself, reconfigure the application to use /opt/tarantella/bin/lp or /opt/tarantella/bin/lpr.

Are Accounts Shared on the Application Server?

If more than one user is simultaneously logged in to the same application server with the same user name, SGD might be unable to distinguish which user owns the print jobs. SGD discards the print jobs, logging that it has done so. This occurs with UNIX or Linux system application servers that do not have an SGD printer queue.

To fix this problem, run the prtinstall.en.sh script to configure a printer. See The SGD Printer Queue Installation Script.

Use the tarantella print command to check that print jobs from the application server printing system are reaching the SGD print queue.

Is the Windows Name of the Server the Same as the DNS Name?

If you have a Microsoft Windows NT server with a DNS name of naples.indigo‐insurance.com and a NetBIOS name of VESUVIUS, print jobs from this server fail, because they contain the host identifier VESUVIUS instead of naples.

You can avoid this problem by editing the file hostnamemap.txt in the /opt/tarantella/etc/data directory. This file enables you to map host names to DNS names. The file contains instructions on how to create the mappings.

If You Are Using PDF Printing, is the Same PostScript Printer Driver Installed on Every Microsoft Windows Application Server?

To be able to use PDF printing, you must install the same PostScript printer driver on every Microsoft Windows application server.

In the Administration Console, check that the name of the driver matches the name configured in the Postscript Printer Driver field on the Global Settings -> Printing tab, or the Printing tab for the user profile or parent object. The System event log on the application server shows an error if the names do not match.

SGD Server Checklist

Use the following SGD server troubleshooting steps to diagnose printing problems in SGD.

Is Printing Paused or Disabled Across the Array?

Use the tarantella print status command to check whether printing is paused or disabled for the array.

If necessary, enable printing, using tarantella print start or tarantella print resume.

For Printing on Microsoft Windows Client Devices, Are Client Printers Disabled?

In the Administration Console, check the Global Settings -> Printing tab, or the Printing tab for the user profile or parent object. See whether users can access all their client printers, just their default client printer, or no client printers.

For PDF printing, check whether the SGD PDF printers are enabled.

Has the Array Configuration Changed?

Printing is not reconfigured if you do any of the following:

  • Create an array

  • Add a new secondary server to the array

  • Change the primary server in the array

If the array has changed you might have to reconfigure printing, so that print jobs are sent to the correct printer.

For PDF Printing, is Ghostscript Available on the SGD Host?

PDF printing in SGD uses Ghostscript to convert print jobs into PDF files. SGD also uses Ghostscript to convert print jobs from PostScript to PCL.

If the /opt/tarantella/var/log/print.log file contains a message such as "Can't find ps2pdf" or "Consider obtaining Ghostscript from http://www.ghostscript.com", then either Ghostscript is not installed or it is installed in a non-standard location.

See Checking the Ghostscript Installation on the SGD Host for details of how fix Ghostscript installation problems.

Tracing a Print Job

If the checklists above do not solve your SGD printing problem, try the following troubleshooting steps. These steps enable you to track the progress of a print job from the application server to the SGD server to the client device.

Step 1: Can You Print From the SGD Server?

Configure an X or character application to run on the SGD server. Display a terminal window, for example xterm, and start the application from your SGD webtop.

Try printing a test page, by running the /opt/tarantella/bin/scripts/printtestpage.en.sh script.

If the page does not print, run /opt/tarantella/bin/scripts/printtestpage.en.sh --direct. This bypasses the UNIX or Linux system spooler.

Check the following:

Step 2: Is the SGD Printer Queue Installed on the SGD Server?

In the list of printers on the SGD host, check for an entry for tta_printer.

Consult your UNIX or Linux system documentation to find out how to display the list of printers. On some systems, you can use lpstat -t. If your system has a file /etc/printcap, this contains a list of printers in plain text format.

Check the following:

Step 3: Is the Print Job Leaving the UNIX or Linux Platform Application Server?

Using an application object configured to display a terminal window on the UNIX or Linux system application server, try printing a small text file to the SGD printer. For example, type the command: lp -d tta_printer /etc/hosts.

Check the following:

Step 4: Is the Print Job Present in the UNIX or Linux System Spool Directory?

The print spool directory varies between different UNIX or Linux systems. Consult your UNIX or Linux system documentation for assistance.

Check the following:

  • Is the print job present in the spool directory?

    There might be a network problem between the application server and SGD server. Go to Step 6: Is the Print Job Reaching the SGD Server?.

  • Is the print job missing from the spool directory?

    Check your UNIX or Linux system LPD printing configuration. For example, ensure that there are suitable entries in /etc/hosts.equiv or /etc/hosts.lpd, and that there are no .deny files, such as /etc/hosts.equiv.deny.

    Check that the lpd daemon is running and listening. For example, use the following commands:


    # ps -ef | grep lpd
    # netstat -a | grep printer
    

    Try printing again.

Step 5: Is the Print Job Leaving the Windows Terminal Services Application Server?

Check the print queue on the application server. Consult your system documentation if you need help on how to do this.

Check the following:

  • Is the print job leaving the application server?

    There might be a network problem between the application server and SGD server. Go to Step 6: Is the Print Job Reaching the SGD Server?.

  • Is the print job leaving the application server?

    Check the configuration of the SGD printer, as follows:

    • Check that you can ping and telnet to the SGD server from the application server.

    • Look for errors in the Event Log.

    • From a command prompt, use the lpr -s server -p tta_printer filename command to print. If this works, the printer driver on the application server might not be installed or configured correctly.

Step 6: Is the Print Job Reaching the SGD Server?

Check the SGD print spool directories on the SGD server: /opt/tarantella/var/spool and /opt/tarantella/var/print/queue.

Check the following:

  • Is the print job present on the SGD server?

    Check that you are using fully qualified DNS names in the application object, and that name resolution is working correctly.

    Examine the printing log files for more information. Go to Step 7: Have You Examined the Print Log Files?.

  • Is the print job missing from the SGD server?

    Check the configuration of the SGD server, as follows:

    • Check your UNIX or Linux system LPD printing configuration.

      For example, ensure that there are suitable entries in /etc/hosts.equiv or /etc/hosts.lpd, and that there are no .deny files, such as /etc/hosts.equiv.deny.

      Check that the lpd daemon is running and listening. For example, use the following commands:


      # ps -ef | grep lpd
      # netstat -a | grep printer
      

    • Check that you can ping and telnet to the SGD server from the application server.

    • If you are using Windows Terminal Services, display a command prompt and use the lpr -s server -p tta_printer filename command to print. If this works, this suggests the printer driver on the application server is not installed or configured correctly.

Step 7: Have You Examined the Print Log Files?

You can use the tarantella query command to examine the logs across the array. Log files are stored in /opt/tarantella/var/log on each SGD server in the array.

If the print log files are empty, edit the Log Filter, to log printing messages. In the Administration Console, go to the Global Settings -> Monitoring tab, and add the following log filters:


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

If the log contains messages indicating problems with user name mappings, this suggests you are using shared accounts on the application server. See Are Accounts Shared on the Application Server?.

Troubleshooting Other Printing Problems

This section describes some typical problems when printing through SGD and includes the following topics.

Troubleshooting Printer Preferences and Settings

When printing from a Windows application that uses the Microsoft RDP Windows Protocol, users can set preferences for the printers they use. The following are common problems with printer preferences.

Current Client Printer Preferences Are Ignored

The first time a client printer is defined for a user, the printer preferences, such as the paper size and orientation, are the application server’s defaults for the printer driver and not the client printer’s current preferences.

Users can change the printer preferences on the application server, and these modified preferences are used when they next connect using a client device with the same printer.

Changes to Printer Preferences Are Not Remembered

When a user changes their printer preferences, for example by changing the default paper size, sometimes the change is not remembered when they next run a Windows application.

There is a delay between changing the preferences and the new preferences being sent to the client. When changing printer preferences, it is advisable to wait a few minutes before logging out of the Windows application.

Printer Preferences Are Lost When a User Changes Printers

Printer preferences are linked directly to the driver name. So, if a user changes the printer they use and the new printer uses a different driver name, they have to set the printer preferences again.

Local Printer Settings Are Not Set in the Remote Windows Application Session

The printer settings of a local printer are not set on the printer in the remote Windows application session when you use SGD. However, they are set when you use the Microsoft Terminal Services Client.

SGD does not support this capability.

Printer Settings Are Ignored When Using PDF Printing

If you are using PDF printing on a Microsoft Windows client device, some printer settings might be ignored by the Adobe Reader.

This might be because the printer driver used for PDF printing has settings that are not available on the client printer.

Some settings, such as page orientation, have to be set in the Adobe Reader print dialog, as well as on the printer in the Windows application session. Once you have set up the Reader, the settings are remembered.

Print Jobs Can Be Queued When SGD Printing is Disabled

After disabling the SGD print system, by running tarantella print stop, it is still possible to spool print jobs on application servers. These jobs remained queued until SGD printing is restarted.

To prevent print jobs from being submitted, disable the SGD print queue manually on the application servers.

Fonts Do Not Print Correctly With PDF Printing

When using PDF printing, users might find that the fonts on the printed output are not what they expected.

As PDF printing relies on a combination of Windows printer drivers, when printing from Windows applications, Ghostscript and a PDF viewer to deliver its output, you might have to experiment with the font settings for each of these components to see if this produces a better result.

TrueType Fonts and Windows Applications

When printing from a Windows application and the document contains TrueType fonts, users might find that the printer is using its own fonts, called device fonts, instead of the TrueType fonts. This can result in some characters being printed as “empty boxes” ([]).

The solution to this problem is to force the printer to download the TrueType fonts for printing.

Display the Print dialog in the Windows application and select Properties -> Advanced. In the Graphic section, change the TrueType Font option to Download as Softfont.

Changing Printer Names in Windows Application Sessions

Printers created in a Windows Terminal Services session have the format "printer‐name (from Sun SGD) in session number". For example, HP LaserJet 8000 Series PS (from Sun SGD) in session 1.

For Unix, Linux, and Mac OS X platform client devices, the printer-name comes from the printer configuration file used for the client device. See Configuring Printing to UNIX, Linux, and Mac OS X Platform Client Devices for more details. For Windows client devices, the printer-name comes from the printer driver.

You can change the Sun SGD part of the printer name by editing the /opt/tarantella/var/serverresources/expect/wcpwts.exp login script. By adding a -netbiosname "name" argument for the ttatsc command, for example -netbiosname "IndigoInsurance", you can change the printer name in the previous example to the following: HP LaserJet 8000 Series PS/IndigoInsurance/Session 1.



Note - The name can only be 15 characters long. If you use more than 15 characters, the name is truncated.



If you are using PDF printing, you can amend the names of the PDF printers. See Changing the Names of the PDF Printers.

Changing the Names of the PDF Printers

The names of SGD PDF printers are configurable. You can amend these names as follows.

To change the PDF printer names for all users, use the following command:


$ tarantella config edit \
--printing-pdfprinter name --printing-pdfviewer name

To change the PDF printer names for an organization, organizational unit, or user profile object, the object must also be configured to override the parent object’s printing settings. Use the following command:


$ tarantella object edit --name object \
--userprintingconfig true --pdfprinter name --pdfviewer name

Users See a Printer Called ‘_Default’ in a Windows Application Session?

Users who access Windows applications from UNIX, Linux, or Mac OS X platform client devices, might see a printer called ‘_Default’ in their Windows application session. This can be confusing to users if their client printer has a different name or they have no client printer.

This is caused by the default setting in the printerinfo.txt file, which is used to associate the printer driver name with a print job when printing from a Windows application.

To correct the printer name, edit the printerinfo.txt file.

To remove the ‘_Default’ printer name, delete the ‘_Default’ entry from the printerinfo.txt file.

See Configuring Printing to UNIX, Linux, and Mac OS X Platform Client Devices, for more details about the printerinfo.txt file.


Client Drive Mapping

Client drive mapping (CDM) enables SGD users to access the drives on their client device from applications running on UNIX, Linux, or Microsoft Windows platform application servers.

This section describes how to configure CDM for SGD users. Common problems when using CDM in SGD are also covered, along with tips on how to fix them.

This section includes the following topics:

Setting Up Client Drive Mapping

Setting up CDM involves the following configuration steps:

  1. Configure the application servers for CDM.

    The SGD Enhancement Module must be installed on the application server.

  2. Enable CDM services in SGD.

  3. Configure the drives you want users to access from SGD.

Configuring UNIX and Linux Platform Application Servers for CDM

Configuring UNIX and Linux platform application servers for CDM involves the following steps:

  1. Install the SGD Enhancement Module for UNIX and Linux Platforms.

    The Sun Secure Global Desktop 4.5 Installation Guide has details of how to install the Enhancement Module.

    See Supported Installation Platforms for the SGD Enhancement Module for information on the supported platforms for the SGD Enhancement Module.

  2. Configure the Network File System (NFS) share to be used for CDM.

    See Configuring an NFS Share for CDM.

  3. Start the CDM processes on the application server.

    See Starting CDM Processes on the Application Server.

Configuring an NFS Share for CDM

Configuring an NFS share for CDM involves the following:

Configuring a Shared Directory on the Application Server

You must have an NFS server installed and running on the application server. The NFS server must share, or export, a directory to be used for CDM. By default, the directory is /smb. You have to manually create and export this directory.

You can specify an alternative NFS share in the CDM configuration file, /opt/tta_tem/etc/client.prf. Edit the [nfsserver/mount/mountpoint={(/smb)}] setting to reflect the name of the share.

The NFS share must be accessible to localhost, and users must have read and write access to it. Consult your system documentation for details of how to configure an NFS server and export a directory.

Configuring How Client Drives Are Displayed on UNIX Platforms

When CDM is enabled, the user’s client drives or file systems are available by default in the My SGD Drives directory in the user’s home directory. The My SGD Drives directory is a symbolic link to the NFS share that is used for CDM.

You can configure the name and location of the symbolic link by adding settings to the CDM configuration file, /opt/tta_tem/etc/client.prf, as follows:

  • The name of the symbolic link. This is configured with the following setting:

    [nfsserver/user/symlinkname={(symlink)}]

    The default setting is: My SGD Drives

    For example, to change the name of the symbolic link to Client Shares, add the following line to the configuration file:

    [nfsserver/user/symlinkname={(Client Shares)}]

  • The directory where the symbolic link is created. This is configured with the following setting:

    [nfsserver/user/symlinkdir={(dir)}]

    The default setting is: $HOME

    For example, to create the symbolic link in the /tmp directory, add the following line to the configuration file:

    [nfsserver/user/symlinkdir={(/tmp)}]

    The directory can also be specified using environment variables. The variables you can use are controlled by the nfsserver/user/envvars setting.

    For example, to create the symbolic link in the /tmp/username directory, add the following line to the configuration file:

    [nfsserver/user/symlinkdir={(/tmp/$USER)}]

  • Environment variables for specifying the directory where the symbolic link is created. These are configured with the following setting:

    [nfsserver/user/envvars={(var)...}]

    The default setting is: (USER)(HOME)(LOGNAME)

    Enclose each variable in parentheses. Do not include the dollar sign ($) before the variable name.

    The variables in the list replace the default variables.

    For example, to be able to use the HOME, USER, DISPLAY and TMPDIR variables, add the following line to the configuration file:

    [nfsserver/user/envvars={(HOME)(USER)(DISPLAY)(TMPDIR)}]

After making any changes to the CDM configuration file, you must restart the CDM processes on the application server. See Starting CDM Processes on the Application Server for details of how to do this.

Starting CDM Processes on the Application Server

To start the CDM processes on the application server, log in as superuser (root) and use the following commands:


# /opt/tta_tem/bin/tem stopcdm
# /opt/tta_tem/bin/tem startcdm

Configuring Microsoft Windows Application Servers for CDM

Configuring Microsoft Windows application servers for CDM involves the following steps:

  1. Install the SGD Enhancement Module for Windows.

    The Sun Secure Global Desktop 4.5 Installation Guide has details of how to install the Enhancement Module.

    See Supported Installation Platforms for the SGD Enhancement Module for information on the supported platforms for the SGD Enhancement Module.

  2. (Optional) Reconfigure the application server’s drives.

    See Remapping or Hiding Microsoft Windows Application Server Drives.

CDM is only available for Windows applications that are configured to use the Microsoft RDP Windows Protocol.

Remapping or Hiding Microsoft Windows Application Server Drives

By default, a Microsoft Windows application server’s drives are also listed when users access their client drives from a Windows application. If you want users to see familiar drive letters, such as drive A for their client’s floppy drive, you can configure the application server to remap its drive letters or hide its drives.

On a Microsoft Windows application server, you can use the Computer Management tools to do the following:

  • Disable drives A and B

  • Disable or remap any CD or DVD drives

  • Remap hard drives

To ensure consistency for users, remap or disable drives in the same way on all Microsoft Windows application servers used for CDM. See your system documentation for more information about remapping and disabling drives.

For information on hiding drives, so that users can only access a limited set of drives, see Using Group Policy Objects to Hide Specified Drives (Microsoft KB article 231289).

Enabling CDM Services in SGD

This section describes how to enable CDM services for an array of SGD servers.

In a default installation, you cannot use CDM and run another Server Message Block (SMB) service, such as Samba, on the SGD host. This is because they both use Transmission Control Protocol (TCP) port 139. To use CDM, you must either disable the other SMB server or configure the host to enable more than one service to use TCP port 139.

To enable more than one service to use TCP port 139, you have to configure the SGD host to have more than one Internet Protocol (IP) address. To do this, either install another network interface card (NIC), or use IP aliasing to assign multiple IP addresses to a single NIC. This is described in How to Run CDM and Another SMB Service on the Same Host.

procedure icon  How to Enable SGD Client Drive Mapping Services

  1. In the Administration Console, display the Global Settings -> Client Device tab.

  2. Configure the following attributes.

    • Client Drive Mapping. Select the Enabled check box.

    • Fallback Drive Search. Choose a drive letter to Start at and a Direction.

      These settings are used for Microsoft Windows client devices only.

      If the desired drive letter is already allocated on a Microsoft Windows application server, the first available fallback drive letter is allocated instead. By default, this is drive V, then drive U, then drive T, and so on.

    • Windows Internet Name Service (WINS). This setting is optional.

      Enabling WINS can improve CDM performance. Only enable WINS if either of the following is true:

      • Your Microsoft Windows application servers are on the same subnet as an SGD server.

      • Your Microsoft Windows application servers list an SGD server as a WINS server.

  3. Either restart all the SGD servers in the array, or use the tarantella start cdm command on each SGD server in the array.

    If you restart the SGD servers, 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.

    If you enable WINS, you must restart your SGD servers.



    Note - Changes made only take effect for new user sessions.



procedure icon  How to Run CDM and Another SMB Service on the Same Host

Repeat this procedure for each SGD server that also has an SMB service enabled.

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. Stop the SGD server and configure the IP addresses you want it to bind to for CDM.

    Use the following command:


    # tarantella config edit \
    --tarantella-config-cdm-externalnbtaddress ip-address ...
    

    The default setting for ip-address is *, which means bind to all interfaces. Separate each IP address with a space.

  2. When you have configured the IP addresses, start the SGD server.

  3. Configure the other SMB service, or services, to bind to a different IP address.

Configuring the Drives Available to UNIX, Linux, and Mac OS X Platform Client Devices

By default, users with UNIX, Linux, and Mac OS X platform client devices have access to their home directory and this is mapped to a drive called My Home.

Users can configure which part of their client file system they can access from applications by editing the $HOME/.tarantella/native-cdm-config configuration file. This file is automatically created when the SGD Client is installed. The file contains detailed instructions for users on how to create mapped drives.

The configuration file contains entries of the form <path> <type> <label> where:

Use a separate line for each drive and separate each of the fields with a space or a tab. If either the <path> or the <label> fields contains spaces or tabs, enclose the field in quotes.

You can use environment variables in the <path> or <label> fields. You delimit these with a dollar sign ($). To use a literal $, escape it with another $.

The following is an example configuration file:

[CDM]
$HOME$ fixed "My Home"
/tmp/$USER$ fixed Temp
"/mnt/win/My Documents" fixed "My Local Documents"
[/CDM]



Note - Changes to the configuration file only take effect for new user sessions.



The access rights for a mapped client drive are shown in brackets after the drive name: (rw)means read-write access, (ro) means read only access.

Configuring the Drives Available to Microsoft Windows Client Devices

For Microsoft Windows client devices, you configure the drives you want users to access with the Client Drive Mapping attribute on the Client Device tab for user profiles, organizational unit, and organization objects. CDM uses inheritance. You define access to client drives at an organization level, which you can override at an organizational unit level or user profile level. By default, users have read and write access to all drives.

For Windows applications, you can configure application-specific client drive access with the Client Drive Mapping attribute on the Client Device tab for the Windows application object. This overrides any CDM settings configured for organization, organizational unit, or user profile objects. The order of precedence when configuring CDM for Windows application objects is: Windows application -> user profile -> organizational unit -> organization.

When a user logs in to an SGD server, information is gathered about the drives on the client device. For each available drive, the Client Drive Mapping attribute on the user profile is checked. If there is no matching client drive configured, the parent organizational unit’s Client Drive Mapping attribute is checked, and so on up the organizational hierarchy to the organization object.

If a match is found, then the associated access rights are granted for that drive, using the configured drive letter. If that drive letter is already in use on the application server, the Fallback Drive Search attribute on the Global Settings -> Client Device tab in the Administration Console is used to determine the drive letter to use.

The access rights for a mapped client drive are shown in brackets after the drive name: (rw)means read-write access, (ro) means read only access.

At each level in the organizational level, you configure a number of drive mapping specifications. Each of these states a client drive letter, the access rights to that drive, and the application server drive letter to allocate. For example, you might specify that a user has read-write access to client drive A using application server drive Z. The first matching entry in the list is used. Make sure the most specific settings, for example, A or B, appear before more general settings, for example, All Drives.



Note - Changes to client drive specifications only take effect for new user sessions.



An Example of Configuring Drive Availability for Users

The following example shows how to disable access to all client drives for all users in the Indigo Insurance organization. Only a single user in the organization, Ruby Port, is allowed to access her PC’s floppy drive.

In the Administration Console, go to the Client Device tab and display the Client Drive Mapping table for the o=Indigo Insurance organization object. In the Client Drive Mapping table, select the check box next to All Drives. Click the Edit button and set the Access Rights to None. This disables access to all client drives.

In the Administration Console, go to the Client Device tab and display the Client Drive Mapping table for the Ruby Port user profile object. In the Client Drive Mapping table, click the New button and configure the following settings:

  • Client Device Drive. Select A:, the drive letter of Ruby’s floppy drive, or R/W Removable. R/W Removable matches all read-write removable drives, such as floppy drives.

  • Access Rights. Select Read/Write. This gives Ruby full access to the drive, as long as the floppy disk is not write-protected.

  • Application Server Drive Letter. Select Same as Client. With this setting, SGD attempts to use the same drive letters on the application server as are used on the client device.

This gives Ruby Port full access to her PC’s floppy drive on drive A:.

Troubleshooting Client Drive Mapping

The following are common problems when using CDM in SGD:

No Client Drives Are Mapped Within the User’s Session or There Are Fewer Drives Than Expected

Use the following checklist to resolve this problem.

Is the SGD Enhancement Module installed on the application server?

To access client drives from applications displayed through SGD, the SGD Enhancement Module must be installed on the application server.

See Supported Installation Platforms for the SGD Enhancement Module for information on the supported platforms for the SGD Enhancement Module.

Is CDM enabled?

In the Administration Console, go to the Global Settings -> Client Device tab and ensure that the Client Drive Mapping check box is selected.

Remember, CDM services only become available when you restart all SGD servers in the array. To manually start CDM services without restarting the array, run the tarantella start cdm command on all members of the array.

Have the user’s client drives been configured correctly?

For users with Microsoft Windows client devices, the Client Drive Mapping attribute on the Client Device tab for organization, organizational unit, and user profile objects determines which client drives each user can access. The user might be configured to have no access to any client drives. Remember to check the ancestor OUs in the organizational hierarchy. CDM settings are inherited, so you can give access to many users with one configuration change.

For Windows applications, application-specific client drive access can be configured using the Client Drive Mapping attribute on the Client Device tab for the Windows application object. Remember that this overrides any CDM settings configured for organization, organizational unit, or user profile objects.

For users with UNIX, Linux, or Mac OS X platform client devices, check that the user’s $HOME/.tarantella/native-cdm-config file is present and has valid entries.

Are CDM processes running?

On the host where SGD is installed, use the following command:


# ps -ef | grep ttacdmd

If CDM processes are running, there are at least two processes with the name ttacdmd.

If there are no any drive mapping processes, use the following command:


# grep cdm /opt/tarantella/var/log/*

Check the output for any messages.

On UNIX and Linux platform application servers, use the following command to check that CDM processes are running:


# /opt/tta_tem/bin/tem status

If CDM processes are not running, use the following command:


# /opt/tta_tem/bin/tem startcdm

If starting CDM processes produces errors such as "Failed to mount /smb", check that the NFS server is running and that the directory being used for CDM is exported correctly.

Check whether another service is using port 4242. If so, edit the /opt/tta_tem/etc/client.prf file and change the port number in the line [nfsserver/mount/port={(4242)}] and restart the CDM processes.

On Microsoft Windows application servers, use Task Manager to check that there is a ttatdm.exe process for the user.

Are you using a proxy server?

Proxy servers drop a connection after a short period of time if there is no activity on the connection.

SGD sends keepalive packets to keep the connection open between the client device and the SGD server and by default this is every 100 seconds. This connection is used for CDM. Try increasing the frequency of the keepalive packets.

See also Proxy Server Timeouts.

Do the version numbers for the SGD Enhancement Module and the SGD server match?

Run the following command on the host where SGD is installed:


$ tarantella version

Make a note of the version number.

On Microsoft Windows application servers, browse to the C:\Program Files\Tarantella\Enhancement Module directory. Click the right mouse button on the ttatdm.exe file and select Properties. On the Version tab, click File Version.

On UNIX or Linux platform application servers, run the following command:


$ /opt/tta_tem/bin/tem version

Are other services using TCP ports 139 and 137?

SGD CDM services must bind to TCP port 139, which is used for SMB services. This port might already be in use, for example by a product such as Samba. User Datagram Protocol (UDP) port 137 is also used if the Windows Internet Name Service (WINS) check box is selected on the Global Settings -> Client Device tab in the Administration Console.

To find out whether any other process is using ports 139 and 137, stop the SGD server and then run the following commands on the host where SGD is installed:


$ netstat -an | grep 139
$ grep 139 /etc/xinetd.conf

To ensure that CDM services are available, stop any other products that bind to TCP port 139 and TCP port 137, if required, and restart the SGD server.

Follow the instructions in How to Run CDM and Another SMB Service on the Same Host.

Have all the client drives been found?

For Windows client devices, the SGD Client displays information about the drives it has found. Click the right mouse button on the System Tray icon and select Connection Info.

For UNIX and Linux platform client devices, this information is written to the SGD Client log file.

Does logging reveal any errors?

Check the CDM log files for any errors, as follows:

  • Microsoft Windows application servers. Check the Windows Event Viewer for any drive mapping errors.

  • UNIX or Linux platform application servers. Check for any drive mapping errors in the clerr.log and the clPID.log files in the /opt/tta_tem/var/log directory.

See also Logging for CDM.

Is the drive mapping connection between the application server and the SGD server working?

Use the diagnostics feature of the application server, as follows:

  • Microsoft Windows application servers. To check whether the drive mapping connection between the application server and the SGD server is working, enable drive mapping in diagnostic mode on the application server. See CDM Diagnostics for Microsoft Windows Application Servers for details. When the drive mapping window displays, select Information from the Debug menu. Check the output for information on why the drive connections are failing.

    Common reasons why drive connections fail for Microsoft Windows application servers include the following:

    • The application server cannot resolve the NetBIOS name of the SGD server. The solution is to configure a WINS server on the application server that points to a WINS server that can resolve the NetBIOS name of the SGD server. Alternatively, edit the lmhosts file to include the NetBIOS name and the IP address of the SGD server.

    • The ttacdmd program is not running, because another SMB server is running.

  • UNIX or Linux platform application servers. Drive mapping errors are reported to the clerr.log and the clPID.log files in the /opt/tta_tem/var/log directory. See also CDM Diagnostics for Unix or Linux Platform Application Servers.

Invalid Password Errors on Microsoft Windows Application Servers

If no client drives are mapped in the Microsoft Windows application session and you see errors such as Add device failed with ERROR_INVALID_PASSWORD in the CDM log output, this can be caused by either of the following:

  • SMB packet signing. Microsoft Windows application servers can be configured so that the SMB communications between a client and Microsoft Windows server are digitally signed for security.

    SGD does not support SMB packet signing. The solution is to disable SMB packet signing.

    See this Microsoft TechNet article for information on disabling SMB packet signing.

  • LAN Manager authentication level. The LAN Manager authentication level controls the authentication protocols used for communications between a client and Microsoft Windows server. If the authentication level is set too high, CDM fails.

    The solution is to edit the Security options\Network security\LAN Manager authentication level policy and select Send LM & NTLM - Use NTLMv2 session security if negotiated.

    See Microsoft KB article 823659 for more details.

See also Logging for CDM.

Windows Client Drives Are Mapped Using Unexpected Drive Letters

If a drive letter is already in use on the Microsoft Windows application server, the drive cannot be remapped automatically. For example, drive A might be reserved for the application server’s floppy drive. The CDM service uses a Fallback Drive to ensure the client drive can be accessed using a different drive letter.

To help ensure that the configured drive letter is available, it is best to hide or remap application server drives to use different drive letters. See Remapping or Hiding Microsoft Windows Application Server Drives.

More Client Drives Are Mapped Than Expected

For users with Microsoft Windows client devices, client drives are inherited within the organizational hierarchy, so you can give access to many users with one configuration change. Check the Client Drive Mapping attribute on the organizational unit object that the user profile object belongs to. If necessary, check all ancestors of the user profile, including the top-level organization object. You can override a setting that is specified in a parent organizational unit (OU) or organization object, by configuring the user profile’s Client Drive Mapping attribute. The first matching drive specification is used.

For users with UNIX, Linux, or Mac OS X platform client devices, check that the user’s $HOME/.tarantella/native-cdm-config file is present and has valid entries.

The Recycle Bin Does Not Work As Expected

On Microsoft Windows client devices, client drives accessed through SGD are treated by the application server as network drives. This means that Recycle Bin features are not available for client drives.

Deleting a file does not send the file to the Recycle Bin. The Recycled directory, if present, is not shown as the Recycle Bin, and its contents are not displayed.

Mapped Drives Have Unusual Names

On Microsoft Windows client devices, sometimes drives appear with unusual names. This is caused by the drive mapping application timing out.

The solution is to increase the default timeout values in the Microsoft Windows registry for the CDM application, ttatdm.exe, on the Microsoft Windows application server. Edit the following settings for the HKEY_LOCAL_MACHINE\Software\Tarantella, Inc.\Enhancement Module for Windows key in the Windows registry:

  • Initial Timeout. The default value is 10000 milliseconds. Increase this value.

  • Subsequent Timeout. The default value is 1000 milliseconds. Increase this value, for example, to 8000 milliseconds.



Note - Changes made only take effect for new user sessions.



On UNIX, Linux, and Mac OS X platform client devices, the names of mapped drives are configured in the user’s $HOME/.tarantella/native-cdm-config file. Check that this file has valid entries.

CDM Limitations for Shared Users

On Unix or Linux platform application servers, access to client file systems is given to users based on their UNIX system user ID and standard NFS file system privileges. If a shared account is used to access applications, CDM is not available. This is because SGD has no way to distinguish between these users, as they all have the same user ID.

Logging for CDM

Logging can be used to diagnose problems with CDM. You configure and use logging for the SGD array and for application servers, as follows:

Enabling CDM Logging for the SGD Array

Add the following filters in the Log Filters field on the Monitoring tab of the Administration Console.


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

CDM Diagnostics for Microsoft Windows Application Servers

On Microsoft Windows application servers, you can run CDM in diagnostic mode, to obtain information for troubleshooting drive mapping problems.

To enable diagnostic mode, log on to the application server as an Administrator and double-click the drive mapping program file, C:\Program Files\Tarantella\Enhancement Module\ttatdm.exe.

When the drive mapping window displays, select the level of information you want, by choosing an option from the Debug menu.

The Debug menu has the following options:

  • Errors. Select this option to see any errors that have occurred. This also causes errors to be reported to the Windows Event Viewer. This option is selected by default.

  • Warnings. Select this option to see any errors and warnings that have occurred. This also causes errors and warnings to be reported to the Windows Event Viewer.

  • Information. Select this option to display all drive mapping information.

  • Log to file. Select this option to save the output to a log file in the user’s temp directory. The drive mapping window shows you the name and location of the log file it has written.

  • Start visible. Select this option to have the drive mapping window display every time the drive mapping services are started.

The drive mapping window only shows drive mapping information from when the window is displayed. It does not show historical information. If you change the level of information displayed in the drive mapping window, the user needs to log out of Windows and log in again to generate the new information.

The Edit menu enables you to select, copy, and clear information from the drive mapping window.

CDM Diagnostics for Unix or Linux Platform Application Servers

On UNIX or Linux platform application servers, drive mapping errors are reported to the clerr.log and the clPID.log files in the /opt/tta_tem/var/log directory.


Audio

This section describes how to configure SGD audio services for Windows applications and X applications. Troubleshooting information for SGD audio is also included.

The following topics are covered:

Setting Up Audio

Setting up audio involves the following configuration steps:

  1. Configure the application servers for audio.

  2. Configure X application objects to use the correct audio device and audio format.

    See Configuring X Applications for Audio.

  3. Enable the SGD audio services.

    See Enabling SGD Audio Services.

  4. Configure the client device to play audio.

    See Configuring Client Devices for Audio.

Configuring Microsoft Windows Application Servers for Audio

To use audio, Windows application objects must be configured to use the Microsoft RDP protocol.

You can only play audio if audio redirection is enabled on the Windows Terminal Server. See Configuring Microsoft Windows Terminal Services for Use With SGD for details of the Windows platforms that support audio redirection.

Configuring UNIX and Linux Platform Application Servers for Audio

To be able to hear audio in an X application, you must install and run the audio module of the SGD Enhancement Module on the UNIX or Linux platform application server.

Installing the Audio Module

See the Sun Secure Global Desktop 4.5 Installation Guide for instructions on installing the audio module. If you did not install the audio module when you installed the SGD Enhancement Module, you must uninstall the SGD Enhancement Module and install it again.



Note - If you are using zones on Solaristrademark Operating System (Solaris OS) platforms, the audio module must be installed in the global zone.



The audio module installs the SGD audio daemon and audio driver emulator. On Linux platforms, the audio driver emulator requires the soundcore module in the kernel. The audio driver emulator is an Open Sound System (OSS) emulator.



Note - As the audio module includes an audio driver emulator, the application server itself does not actually need to have a sound card.



Starting the Audio Module

If the audio module is installed, you start the audio service with the /opt/tta_tem/bin/tem startaudio command. You must be superuser (root) to use this command.

About the SGD Audio Daemon

When audio is enabled and the user starts an X application, the SGD login script starts the SGD audio daemon, sgdaudio, on the application server.

The audio daemon connects to an SGD audio driver emulator, sgdadem, and starts an audio device node in the /tmp/SGD/dev/sgdaudio directory. The audio daemon sets the SGDAUDIODEV, AUDIODEV, and AUDIO environment variables to the location of the audio device node. The audio device node is then used to play audio during the application session.

The audio daemon transfers the audio data to the SGD server, which then sends the data to the client.

The audio daemon supports the following audio data formats:

  • u-law and A-law with 8-bit precision

  • 16-bit linear Pulse-code modulation (PCM)

To play audio, the client device must also support these formats.

The audio daemon supports any sample rate from 8000 Hz to 48 kHz for one or two channels. The audio daemon uses the sample rate specified by the UNIX Audio Sound Quality attribute on the Global Settings -> Client Device tab in the Administration Console. By default, the sample rate is 22.05kHz.

The SGD audio daemon connects to the SGD server on random ports. If there is a firewall between the application server and the SGD server, the firewall must allow connections on all ports from the application server to the SGD server.

Configuring X Applications for Audio

To be able to hear audio in an X application, the X application might have to be configured to output audio using the right audio device and audio format.

Some X applications are hard-coded to use the /dev/audio or /dev/dsp devices for audio output. You can enable an SGD audio redirection library, to force the X application to use the device specified by the SGDAUDIODEV environment variable.

In the Administration Console, go to the Client Device tab for the X application and select the Audio Redirection Library check box.

Alternatively, use the following command:


$ tarantella object edit --name obj --unixaudiopreload true

As the SGD audio driver emulator is an OSS driver, the X application might have to be configured to use OSS. If your system uses the Advanced Linux Sound Architecture (ALSA), you might have to enable the ALSA OSS emulation modules in the kernel.

If the Connection Method (--method) used for the X application is SSH and the application’s Window Type (--displayusing) is Kiosk, the Session Termination (--endswhen) attribute must be set to Login Script Exit or No Visible Windows (--loginscriptnowindows).

Enabling SGD Audio Services

To be able to hear audio in Windows applications and X applications, audio services must be enabled for the SGD array.

Firewalls between SGD servers can interfere with the connections required for Windows audio, seeFirewalls Between SGD Servers.

procedure icon  How to Enable the SGD Windows Audio Service

To be able to hear audio in a Windows application, the SGD Windows audio service must be enabled in the array. The Windows audio service is disabled by default.

  1. In the Administration Console, go to the Global Settings -> Client Device tab and select the Windows Audio check box.



    Tip - You can also use the tarantella config edit --array-audio command to enable the SGD Windows audio service.





    Note - The audio service only takes effect for new user sessions. Users must log out of SGD and log back in again to enable audio in their current Windows Terminal Server sessions.



  2. Set the audio quality.

    Select an option for Windows Audio Sound Quality.

    The default is Medium Quality Audio, using a sample rate of 22.05kHz. Only change this setting if you experience problems with audio quality.

procedure icon  How to Enable the SGD UNIX Audio Service

To be able to hear audio in an X application, the SGD UNIX audio service must be enabled in the array. The UNIX audio service is disabled by default.

  1. In the Administration Console, go to the Global Settings -> Client Device tab and select the Unix Audio check box.



    Tip - You can also use the tarantella config edit --array-unixaudio command to enable the SGD UNIX audio service.





    Note - The audio service only takes effect for new user sessions. Users must log out of SGD and log back in again to enable audio in their X application sessions.



  2. Set the audio quality.

    Select an option for Unix Audio Sound Quality.

    The default is Medium Quality Audio, using a sample rate of 22.05kHz. Only change this setting if you experience problems with audio quality.

Configuring Client Devices for Audio

To be able to hear audio in an Windows application or X application, the client device must be capable of playing audio.

Users with Solaris OS or Linux platform client devices must have read and write access to the following audio devices:

For Linux platform client devices, the Enlightened Sound Daemon, also known as ESD or EsounD, must be running on the client device.

ESD is usually started when the client device desktop session is started. Otherwise, the daemon must be autospawned by the ESD library on request. Ensure that autospawning is enabled in the ESD configuration file, /etc/esd.conf. The correct setting is auto_spawn=1.

Audio mixing on the client device is supported. On Solaris OS workstations, Microsoft Windows, and Mac OS X client devices, the client hardware performs the mixing. On Linux and SunRay client devices, ESD is required to perform mixing.

Troubleshooting Audio in Applications

The following are common problems when using audio in Windows applications and X applications:

No Audio Plays At All

If no audio is playing at all in the application session, use the following checklist to resolve the problem.

For Windows applications and X applications, you can use the following checklist.

Does the client device have an audio device?

To be able to play audio, the client device must have an audio device. If there is an audio device, check that it works.

Users with Solaris OS or Linux platform client devices must also have read and write access to the following audio devices:

  • The /dev/audio device on Solaris OS platforms

  • The /dev/dsp device on Linux platforms



Note - On Solaris OS platforms, if the AUDIODEV environment variable has been set to a different device, the SGD Client tries to use this device before trying the /dev/audio device.



For Linux platform client devices, is ESD running?

For Linux platform client devices, ESD must be running.

Use the following command to check if ESD is running:


$ ps -ef | grep esd

ESD is usually started when the client device desktop session is started. If ESD is not running, check that autospawning is enabled in the ESD configuration file, /etc/esd.conf. The correct setting is auto_spawn=1.

Is the volume muted on the client device?

Check the volume control on the client device, to see whether the user has muted the volume or set the volume level too low to hear.

Is the volume muted on the application server?

Check the volume control on the application server, or in the application, to see whether the user has muted the volume or set the volume level too low to hear.

Has the audio service been enabled on the SGD server?

By default, SGD audio services are disabled for an SGD array.

See How to Enable the SGD Windows Audio Service for details of how to enable the SGD Windows audio service.

See How to Enable the SGD UNIX Audio Service for details of how to enable the SGD UNIX audio service.

Has the audio quality been changed?

By default, the SGD audio service uses Medium Quality Audio. Changing the audio quality to Low Quality Audio or High Quality Audio limits the audio formats used in the application session and might mean that the client device cannot play audio.

Reset the audio quality to Medium Quality Audio on the Global Settings -> Client Device tab in the Administration Console.

For Windows applications, is audio redirection enabled on the application server?

You can only play audio if audio redirection is enabled on the Windows Terminal Server. See Configuring Microsoft Windows Terminal Services for Use With SGD for details of the Windows platforms that support audio redirection.

Audio redirection is disabled by default on Windows Terminal Servers.

For Windows applications, is there a firewall between the SGD server hosting the user session and the SGD server hosting the application session?

For Windows applications, firewalls between SGD servers can interfere with audio connections, seeFirewalls Between SGD Servers.

For X applications, is there a firewall between the application server and the SGD server?

For X applications, the SGD audio daemon connects to the SGD server on random ports. If there is a firewall between the application server and the SGD server, the firewall must allow connections on all ports from the application server to the SGD server.

For X applications, have you installed the audio module of the SGD Enhancement Module?

To be able to play sound in X applications, you must install and run the audio module of the SGD Enhancement Module on the application server.

See the Sun Secure Global Desktop 4.5 Installation Guide for details of how to install the SGD Enhancement Module.



Note - If you are using zones on Solaris OS platforms, the audio module only works if it is installed in the global zone.



Use the following command to check that UNIX audio processes are running:


$ /opt/tta_tem/bin/tem status

You start the UNIX audio module with the following command:


# /opt/tta_tem/bin/tem startaudio

You must be superuser (root) to use this command.

Is the X application hard-coded to use either the /dev/audio or the /dev/dsp device?

If an application is hard-coded to use either the /dev/audio or the /dev/dsp device, you might have to enable the SGD audio redirection library to ensure that the SGD audio driver emulator is used by the application. See Configuring X Applications for Audio.

Is the X application outputting sound in the right format?

The SGD audio driver emulator is an OSS driver. The X application might have to be configured to use OSS. If your system uses ALSA, you might have to enable the ALSA OSS emulation modules in the kernel.

For UNIX or Linux platform application servers, is the SGD audio driver loaded in the kernel?

When you install the SGD Enhancement Module on the application server, you install the SGD audio driver, sgdadem. Check that the audio driver is loaded in the kernel.

  • On Solaris OS platforms, use the modinfo -c command to check whether the sgdadem module is loaded.

  • On Linux platforms, use the lsmod command to check whether the sgdadem and soundcore modules are loaded.

If the audio driver is installed but not loaded, you can try to load the module manually, as follows:

  • On Solaris OS platforms, use the modload -i moduleID command. Use the modinfo -c command to find the moduleID.

  • On Linux platforms, use the modprobe sgdadem command.

If loading the audio driver manually produces any errors, try to correct those errors and load the driver again.

If the SGD audio driver is not listed, check the audio module installation log for any errors. The installation log is /opt/tta_tem/var/log/tem_unixaudio_inst.log. If the log reports any errors, try to correct those errors and load the driver again.

If the audio driver does not load into the kernel, contact Sun Support.

For X applications, is the SGD audio daemon running on the application server?

There is an SGD audio daemon, called sgdaudio, running for each X application accessed through SGD. Use the following command to see the instances of the audio daemon:


$ ps -ef | grep -i sgdaudio

If the user does not have an audio daemon, check the audio daemon log files for any errors. The SGD audio daemon logs all fatal errors to the /opt/tta_tem/var/log/sgdaudioPID.log file.

For X applications, is there an SGD audio device node?

If the SGD audio daemon is running, it starts an audio device node in the /tmp/SGD/dev/sgdaudio directory.

In the X application session, check the value of the user’s SGDAUDIODEV, AUDIODEV and AUDIO environment variables. These must be set to the location of the SGD audio device node.

If the environment variables are set correctly, check that the device file is present in the /tmp/SGD/dev/sgdaudio directory.

For X applications, does audio debug logging show any errors with the application?

Enable UNIX audio debug logging on the application server and check the log files for errors.

See Enabling UNIX Audio Debug Logging for more details.

Audio Is Muffled or Distorted

If audio is muffled or distorted, adjust the audio quality and audio compression settings to see if this improves the audio. You can adjust the following:

  • The Sound Quality attribute on the Global Settings -> Client Device tab in the Administration Console

  • The Packet Compression attribute on the Protocol Engines -> Audio tab for an SGD server in the Administration Console



Note - The net gain of compressing audio data, which is precompressed, is limited.



Not All Users Require Audio

If you enable audio on the Windows application server and enable the SGD audio service, all users can play audio in their Windows Terminal Services session. However, playing audio increases the amount of network bandwidth used and so you might want to restrict its use. Currently, the only way to do this is to disable audio for groups of users on the Windows application server. To do this you have to disable the Allow audio redirection setting for the group policy object, at Computer Configuration\Administrative Templates\Windows Components\Terminal Services\Client Server Redirection.

Changes to this setting only apply to new Windows Terminal Server sessions.

Enabling UNIX Audio Debug Logging

To enable UNIX audio debug logging, log in as superuser (root) on the application server and edit the /etc/sgdtem.conf file. Change the value of the SGDUNIXAUDIODEBUG environment variable in this file, as follows:

SGDUNIXAUDIODEBUG=1; export SGDUNIXAUDIODEBUG

To obtain debug logging output, the user must start a new instance of the application. Suspending and resuming the application does not generate any output, as this does not start a new instance of the SGD audio daemon.

The debug logging output goes to the /opt/tta_tem/var/log/sgdaudioPID.log file.


Copy and Paste

This section describes how to configure and control access to copy and paste for applications displayed through SGD. Common problems with copy and paste are also described.

This section includes the following topics:

Using Copy and Paste

Users can copy and paste text between applications displayed through SGD. Users can also copy and paste text between applications running on a client device and applications displayed through SGD. SGD supports the copy and paste of Unicode characters.

Users can only copy and paste graphics to or from Microsoft Windows 2000 or later applications.

For Windows applications and X applications, you copy and paste by using the normal method for the application you are copying from, and then the normal method for the application you are pasting to.

For character applications, click with the right mouse button, and then choose Copy or Paste as appropriate. To select a column of text in a character application, hold down the Shift key while selecting the text.

If a user attempts a copy and paste operation that is not permitted, for example because of differing security levels, they paste the following message instead of the copied data: Sun Secure Global Desktop Software: Copied data not available to this application

SGD Administrators have full control over copy and paste operations in Windows applications and X applications. See Controlling Copy and Paste in Applications.

Controlling Copy and Paste in Applications

In the Administration Console, you can control copy and paste operations for Windows applications and X applications displayed through SGD by doing the following:

Configuring Global Copy and Paste Settings for the SGD Array

On the Global Settings -> Client Device tab, copy and paste for SGD as a whole can be enabled or disabled. By default, copy and paste is enabled.

The Client’s Clipboard Security Level attribute can be used to assign a security level to the SGD Client. Data can only be copied from SGD to applications running on the client device if the SGD Client has the same security level or higher as the source application. This enables SGD Administrators to secure the flow of data outside of SGD. The default Client’s Clipboard Security Level is 3.

Configuring Copy and Paste for Specific Users

On the Client Device tab for organization, organizational unit, or user profile objects, the Copy and Paste attribute can be used to control which users in the organization are allowed to use copy and paste.

The setting for this attribute can be inherited from a parent object in the organizational hierarchy, so that SGD Administrators can enable or disable copy and paste for many users without having to edit each user profile object. By default, copy and paste is enabled.

Configuring Copy and Paste for Specific Applications

On the Client Device tab for Windows application and X application objects, the Copy and Paste attribute can be used to enable or disable copy and paste operations to or from the application.

The application can also be assigned a Clipboard Security Level. Users can only copy and paste data to an application displayed through SGD if it has the same security level or higher as the source application. The source application is the application that the data was copied from. This enables SGD Administrators to secure the data available through particular applications. The default security level is 3.

When configuring security levels, the higher the number, the higher the security level.



Note - Character applications displayed through SGD are treated the same as applications running on the client. This is because character applications use the local client clipboard for copy and paste operations.



An Example of Using Clipboard Security Levels

In this example, copy and paste has been enabled for all users in an organization. The Client’s Clipboard Security Level attribute is set to 3, the default setting. The following table shows the security levels for applications displayed through SGD.


Application Application’s Clipboard Security Level
XFinance 3
XClaim 4
Write-o-Win 4
Slide-o-Win 2

When an SGD user runs these applications, the following copy and paste operations are allowed.


In This Application An SGD User Can Paste Data From These Applications
XFinance
  • Slide-o-Win. It has a lower security level.

  • Applications running on the client device. The client device has equal security level.

XClaim
  • XFinance and Slide-o-Win. They have a lower security level.

  • Applications running on the client device. The client device has a lower security level.

  • Write-o-Win. It has an equal security level.

Write-o-Win
  • XFinance and Slide-o-Win. They have a lower security level.

  • Applications running on the client device. The client device has a lower security level.

  • XClaim. It has an equal security level.

Slide-o-Win
  • Copy and paste is not allowed. All applications and the client device have a higher security level.


Tips on Configuring Copy and Paste

The following are some tips for SGD Administrators who need to configure copy and paste settings for SGD objects.

Copy and Paste Troubleshooting

For Windows applications and X applications, users can only copy and paste text under the following conditions:

If these conditions are not met, users paste the following message, instead of the copied data: Sun Secure Global Desktop Software: Copied data not available to this application

For Windows applications, users you can only copy graphics from, or paste graphics to, Microsoft Windows 2000 or later applications.

To copy and paste Unicode text in X applications, the X application must support Unicode. Common Desktop Environment (CDE) and Motif applications, for example, do not support Unicode.


Smart Cards

This section describes how to configure smart cards for Windows applications displayed through SGD.

This section includes the following topics:

Using Smart Cards With Windows Applications

SGD enables users to access a smart card reader attached to their client device from applications running on a Windows application server. Users can do the following:

See Smart Cards Supported by SGD for details of the smart cards that have been tested successfully with SGD.

Smart Cards Supported by SGD

SGD works with any Personal Computer/Smart Card (PC/SC)-compliant smart card and reader.

Logging in to a Windows application server using a smart card has been tested successfully with the smart cards listed in the following table.


Client Operating System and Libraries Smart Card
Microsoft Windows XP Vista ActivCard 64K

CryptoFlex 32K

GemPlus GPK16000

Microsoft Windows XP Professional ActivCard 64K

CryptoFlex 32K

GemPlus GPK16000

Microsoft Windows 2000 Professional ActivCard 64K

CryptoFlex 32K

GemPlus GPK16000

Solaris OS with Sun Raytrademark thin client PC/SC Bypass package (SUNWsrcbp) ActivCard 64K

CryptoFlex 32K

Fedora Linux with pcsc-lite 1.2.0 ActivCard 64K

CryptoFlex 32K

GemPlus GPK16000


Setting Up Access to Smart Cards

SGD Administrators can give users access to smart card readers from Windows applications displayed through SGD. Setting up access to smart cards involves the following configuration steps:

  1. Enable smart card services on the application server.

    See Configuring the Microsoft Windows Application Server for Smart Cards.

  2. Enable access to smart cards for SGD users.

    See Enabling Smart Cards in SGD.

  3. Configure a smart card reader on the client device.

    See Configuring Smart Card Readers on Client Devices.

  4. Log in to the application server using the smart card.

    See How to Log In to a Microsoft Windows Application Server With a Smart Card.

Configuring the Microsoft Windows Application Server for Smart Cards

To configure the Microsoft Windows application server for smart cards, do the following:

Application Server Authentication Dialog Settings

In the Administration Console, the Global Settings -> Application Authentication tab has several attributes that control the behavior of the Application Server Authentication dialog when using the SGD smart card service.

The Smart Card Authentication check box controls whether users get the choice of logging in with a smart card or only with a user name and password.

The "Always Use Smart Card" Box attributes enable you to control whether a user’s decision to log in with a smart card is remembered, or cached, for the next time they log in to that application server, and whether they can change this setting.



Note - Users can only choose an authentication method, or to cache the smart card decision, if they have access to the Application Server Authentication dialog. If you disable the ability to use Shift-click, this restricts user access to the Application Server Authentication dialog. See Users Can Start Applications With Different User Names and Passwords.



Enabling Smart Cards in SGD

SGD must be configured in order to support user access to smart cards.

Firewalls between SGD servers can interfere with the connections required for smart cards, seeFirewalls Between SGD Servers.

procedure icon  How to Enable Smart Cards in SGD

  1. Check that the SGD smart card service is enabled.

    In the Administration Console, go to the Global Settings -> Client Device tab, ensure the Smart Card check box is selected.

    The smart card service is enabled by default.

  2. Ensure that Windows applications that require smart cards are configured to use Microsoft RDP Protocol as the Windows Protocol (--winproto).

  3. Ensure that smart card authentication is enabled.

    Smart card authentication is enabled by default.

    In the Administration Console, go to the Global Settings -> Application Authentication tab, ensure the Smart Card Authentication check box is selected.

    The Global Settings -> Application Authentication tab has other settings that affect the behavior of the Always Use Smart Card check box on the Application Server Authentication dialog. See Application Server Authentication Dialog Settings.

Configuring Smart Card Readers on Client Devices

SGD works with PC/SC-compliant cards and readers. See the PC/SC Workgroup web site for more information.

The smart cards supported by SGD are listed in Smart Cards Supported by SGD.

Microsoft Windows Client Devices

On Microsoft Windows client devices, you must install the smart card reader and any required drivers on the client device to make the smart card available to Terminal Services sessions running through SGD.

Linux Platform and Solaris OS Client Devices

On Linux platform and Solaris OS client devices, a PCSC-Lite library must be installed for SGD to communicate with smart card readers. PCSC-Lite provides an interface to the PC/SC framework on UNIX and Linux platforms.

For Linux platform client devices, PCSC-Lite is available from the following locations:

PCSC-Lite version 1.2.0 or later is required.

For Solaris OS client devices, PCSC-Lite compatible libraries are available in the following packages:

  • The PC/SC Shim for SCF package (PCSCshim)

  • The Sun Ray PC/SC Bypass package (SUNWsrcbp)

The PC/SC Shim for SCF package enables you to use a PC/SC application with the Solaris Card Framework (SCF) and work with Sun internal readers and Sun Ray readers. Version 1.1.1 or later is required. PC/SC Shim is included with Solaris 10. For other Solaris versions, PC/SC Shim is available from the MUSCLE project.

The Sun Ray PC/SC Bypass package provides a PCSC-Lite interface for the Sun Ray reader. Make sure you have the latest patches for Sun Ray Server Software and the latest SUNWsrcbp package.

SGD clients require the PCSC-Lite libpcsclite.so library file. This is normally installed in /usr/lib, but the location depends on your dynamic linker path. If this file is installed outside of the dynamic linker path, or you want to use a different library file, use the TTA_LIB_PCSCLITE environment variable to specify the location. This can be set either in the user’s environment or in the login script.

procedure icon  How to Log In to a Microsoft Windows Application Server With a Smart Card

  1. Log in to SGD.

  2. On the webtop, click the link to start the Windows application.

  3. When the Application Server Authentication dialog displays, click Use smart card.

  4. To always use a smart card to log in, click the Always use smart card box.

  5. When the Windows security dialog displays, insert your smart card.

  6. When prompted, enter your PIN.

Troubleshooting Smart Cards

For information about configuring SGD to use smart cards with Windows applications see Using Smart Cards With Windows Applications.

If users find they are unable to use their smart cards with Windows applications, use the following checklist to resolve the problem.

Is the smart card device redirection enabled on the Windows Terminal Server?

You can only use smart cards if smart card device redirection is enabled on the Windows Terminal Server. See Configuring Microsoft Windows Terminal Services for Use With SGD for details of the Windows platforms that support smart card device redirection.

Does the Windows application use Microsoft RDP as the Windows Protocol?

In the Administration Console, go to the Launch tab for the Windows application object and check that the Windows Protocol attribute is set to Microsoft RDP Protocol.

Are smart card services enabled for all SGD servers in the array?

In the Administration Console, go to the Global Settings -> Client Device tab, ensure the Smart Card check box is selected.

In the Administration Console, go to the Global Settings -> Application Authentication tab, ensure the Smart Card Authentication check box is selected.

Is there a firewall between the SGD server hosting the user session and the SGD server hosting the application session?

Firewalls between SGD servers can interfere with smart card connections, seeFirewalls Between SGD Servers.

Is the client device configured correctly?

On Microsoft Windows client platforms, do the following:

  • Check that the smart card reader is listed in the Windows Device Manager.

  • Check that the smart card service is running on the client. Click Start Menu -> Programs -> Administrative Tools -> Services.

  • Check that the SGD Client has detected the smart card reader and card. Click the right mouse button on the SGD icon in the Windows system tray and select Connection info. The Smart card reader property lists the details in the format reader:ATR_string where reader is the manufacturer and model of the smart card reader and ATR_string is the Automatic Terminal Recognition (ATR) string, a sequence of hexadecimal numbers used to identify the card to the system.

On Linux platforms, do the following:

  • Check that the PCSC daemon, pcscd, is running. For example, you can use the following command:


    # /sbin/service pcscd status
    

  • Try restarting the PCSC daemon with a --debug stdout option. Insert the smart card in the reader and see if the reader and card are detected.

On Solaris OS platforms, do the following:

  • If you are using the PC/SC Shim for SCF package, check that the OCF server, ocfserv, is running. If it is not running, use the following command to enable the OCF server:


    # svcadm enable svc:/network/rpc/ocfserv
    

  • If you are using the Sun Ray PC/SC Bypass package, check the Sun Ray Server Software configuration.

Are there any error messages listed in the log file?

Smart card device access data and error messages are stored in the SGD Client log file. This data is displayed in the Detailed Diagnostics page of the SGD webtop.


Serial Ports

This section describes how to set up access to serial ports for Windows applications displayed through SGD.

This section includes the following topics:

Setting Up Access to Serial Ports

Setting up access to serial ports involves the following configuration steps:

  1. Enable COM port mapping on the application server.

    See Configuring the Microsoft Windows Application Server.

  2. Enable access to serial ports for SGD users.

    See Enabling Serial Port Access in SGD.

  3. Configure the client device for serial port access.

    See Configuring the Client Device.

Configuring the Microsoft Windows Application Server

You can only access serial ports if COM port mapping is enabled on the Windows Terminal Server. See Configuring Microsoft Windows Terminal Services for Use With SGD for details of the Windows platforms that support COM port mapping.

To access serial ports, Windows application objects must be configured to use the Microsoft RDP protocol.

Enabling Serial Port Access in SGD

Access to serial ports is enabled for all users by default. If it is disabled, you can enable access to serial ports for all users, or for specific users.

When a user starts a Windows application, SGD checks the user profile for the user and then any parent object further up the organizational hierarchy to see whether access to serial ports is enabled or disabled. If all the objects checked are configured to use the parent’s setting, then the global setting is used.

Firewalls between SGD servers can interfere with the connections required for serial ports, seeFirewalls Between SGD Servers.

procedure icon  How to Enable Access to Serial Ports

  1. In the Administration Console, go to the Global Settings -> Client Device tab and select the Serial Port Mapping check box.

    The Serial Port mapping check box is enabled by default.

  2. In the Administration Console, go to the Client Device tab for an organization, an organizational unit, or a user profile object.

    1. Select the Override Parent’s Settings or Override Global Settings check box.

    2. Set the Serial Port Mapping attribute.

      To enable access to serial ports, select the Enabled check box. To disable access to serial ports, deselect the Enabled check box.

    If you configure an organization or organizational unit object, this affects all the users in that organization or organizational unit.



    Note - The changes made only take effect for new user sessions.



Configuring the Client Device

To determine the serial ports that are mapped in the Windows Terminal Services session, you might have to configure the client device.

On UNIX and Linux client platforms, users must have read and write access to any serial device that is mapped. SGD uses the first match of the following:

  1. The serial ports listed in the SUN_MAP_SERIALPORTS environment variable.

    Each serial port in the list is separated with a semi-colon and has the format serial device=com-port-name. For example:

    /dev/ttyS0=COM1;/dev/ttyS4=COM8

    The =com-port-name part is optional, but if it is omitted the serial port is mapped to COMx in the Windows application session, where x is the position of the serial port in the list.

  2. The serial ports listed in the user’s client profile.

    The <serialports> entry in the <localsettings> section of the user’s client profile lists the serial ports to be mapped. See Client Profile Settings.

    The <serialports> entry has to be added manually.

    The serial ports are listed in the same format as above.



    caution icon

    Caution - If a user has not edited their client profile, any manual changes made to the profile.xml file are lost when the user next logs in.



  3. The serial port listed in the SUN_DEV_SERIAL environment variable.

    This is a single serial device, for example /dev/ttyS2. This is always mapped to COM1 in the Windows application session.

On Microsoft Windows client platforms, SGD uses the first match of the following:

  1. The serial ports listed in the user’s client profile.

    The <serialports> entry in the <localsettings> section of the user’s client profile lists the serial ports to be mapped. See Client Profile Settings.

    The <serialports> entry has to be added manually.

    Each serial port in the list is separated with a semi-colon and has the format serial device=com-port-name.

    COM1=COM5;COM2=COM8

    The =com-port-name part is optional, but if it is omitted the serial port is mapped to COMx in the Windows application session where x is the position of the serial port in the list.



    caution icon

    Caution - If a user has not edited their client profile, any manual changes made to the profile.xml file are lost when the user next logs in.



  2. Any available COM1 to COM9 ports.

    The SGD Client attempts to open ports COM1 to COM9. If a COM port is found, it is mapped to the same COM port number in the Windows application session.