Administrator s Guide. Citrix XML Service For Citrix MetaFrame for UNIX Operating Systems Solaris Intel /Solaris SPARC versions Citrix Systems, Inc.

Administrator s Guide Citrix XML Service For Citrix MetaFrame for UNIX Operating Systems Solaris Intel /Solaris SPARC versions Citrix Systems, Inc.

Information in this document is subject to change without notice. Companies, names, and data used in examples herein are fictitious unless otherwise noted. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Citrix Systems, Inc. 2000 Citrix Systems, Inc. All rights reserved. Citrix, Independent Computing Architecture (ICA), MultiWin, DirectICA, SecureICA, NFuse, Program Neighborhood, MetaFrame and WINFRAME are registered trademarks or trademarks of Citrix Systems, Inc. in the U.S.A. and other countries. UNIX is a registered trademark of The Open Group in the U.S.A. and other countries. Sun, Sun Microsystems, Solaris and Java, are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the United States and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc. All other Trade Names referred to are the Servicemark, Trademark, or Registered Trademark of the respective manufacturers.

Contents iii Chapter1 UsingtheCitrixXMLService... 1 About NFuse.....1 About this Guide...1 AnOverviewoftheCitrixXMLService...2 Requirements...3 Installing the Citrix XML Service....4 Installing the Citrix XML Service....5 StartingtheCitrixXMLService...7 Stopping the Citrix XML Service...8 GuidelinesforCreatingWebPagesforusewithNFuseforUNIX...8 Chapter2 ConfiguringApplications... 9 Overview...9 ConfiguringApplicationSettings...10 ConfiguringhowApplicationsareDisplayed...11 Configuring the Visibility of Applications to Users....12 EnablingorDisablingFiltering...13 ManagingBackupServers...14 Chapter3 CitrixXMLServiceCommandReference... 15 Overview...15 ctxnfusecfg...16 ctxnfuserefresh...19 ctxnfusefilter.....19 ctxnfusesrv...20

1 CHAPTER 1 Using the Citrix XML Service 1 About NFuse About this Guide NFuse is Citrix s tool for deploying applications on MetaFrame servers using the Web. It combines the centralized application management capabilities of Citrix server software with new techniques for Web application deployment into a highly customizable application delivery mechanism. NFuse brings a powerful user interface to the application deployment process. This interface uses Java object technology executed in a Citrix Web Server Extension to dynamically create an HTML-based presentation of the Citrix server farm for each of your users. Included in each user s presentation are all of the applications published in the Citrix server farm for that user. An NFuse deployment consists of three interacting network components: A Citrix MetaFrame server farm. A Web server running the Citrix Web Server Extension. ICA Client devices. The Citrix XML Service runs on one or more of the Citrix MetaFrame servers in the server farm, and communicates information about published applications to the Citrix Web Server Extension. This guide is for Citrix MetaFrame server administrators responsible for setting up the Citrix XML Service in an NFuse system, and deploying applications for access via the Citrix Web Server Extension. This Administrator s Guide includes: An overview of the Citrix XML Service. System requirements and installation instructions.

2 Citrix XML Service for UNIX Administrator s Guide Information about configuring applications for use with NFuse. A reference section describing the use and syntax of each command-line utility. An Overview of the Citrix XML Service The Citrix XML Service for UNIX MetaFrame servers runs as a daemon on one or more of the UNIX MetaFrame Servers in a server farm. The Citrix XML Service communicates information about the UNIX applications published in the server farm to the Web server component of the NFuse deployment. Appropriately configured Web pages on the Web server can then make these applications available to selected users, via a standard Web browser. The Citrix XML Service allows you to make all published applications visible to all users. This is the default when the service is first installed. Alternatively the Citrix XML Service can provide application filtering, allowing you to specify to which users or groups each application is visible. Note Even if a user can see a link to an application in a Web page, they may not be able to run the application unless they have the appropriate access permissions. The Citrix XML Service also allows you to specify the name and icon used to display the link to each application in the Web page, and the default window settings for the application when run. Differences Between the UNIX and NT Versions of the Citrix XML Service There are several important differences between the UNIX and NT versions of the Citrix XML Service, and these are summarised in the following table: Feature MetaFrame for NT MetaFrame for UNIX Information about visibility of applications to users and how applications are displayed. Implementation of the Citrix XML Service. Error reporting. Stored in Windows NT Program Neighborhood. Windows NT system service. Windows NT error log. Stored in local configuration file. UNIX daemon. Syslog.

Chapter 1 Using the Citrix XML Service 3 Feature MetaFrame for NT MetaFrame for UNIX Support for authentication domains. Supports multiple domains. Supports authentication in a single NIS domain. This is the domain containing the UNIX MetaFrame server running the Citrix XML Service. The following features provided in version 1.5 of the NT Citrix XML Service are not currently available in the UNIX version: Support for SSL Relay. Ticketing, avoiding the need to store passwords at the client (for greater security). Ability to view applications by authentication group or folder. Check the Citrix Web site for update information. Constraints on MetaFrame Server Farms A MetaFrame server farm allows published applications to be distributed between a set of multiple UNIX or NT MetaFrame servers. For UNIX MetaFrame servers to be included in a farm they need to be on the same subnet, or connected by Citrix gateways. NFuse allows you to publish UNIX and NT applications to the Web from a mixed server farm provided the NT MetaFrame servers are version 1.8 or above. Creating Web pages To publish applications to the Web from a UNIX MetaFrame server you need to create customised Web pages to suit your requirements. NFuse includes a Web Site Wizard, and several sample Web pages, which are suitable for immediate use with the NT version of the Citrix XML Service, and can be used as a convenient starting point for creating Web pages for use with the UNIX version of the Citrix XML Service. For more information see Guidelines for Creating Web Pages for use with NFuse for UNIX on page 8. Requirements The Citrix XML Service for UNIX requires a Solaris Intel or Solaris SPARC workstation running Solaris 2.6 or later. In addition the following patches are required: OS Version Patch Intel Solaris 6 104678-07 Sparc Solaris 6 105591-09 Intel Solaris 7 106328-08 Sparc Solaris 7 106327-08

4 Citrix XML Service for UNIX Administrator s Guide These can be downloaded from the Solaris Web site at http://sunsolve.sun.com/. The server should be running MetaFrame for UNIX version 1.1 or later. If the server is part of a MetaFrame server farm, it is recommended that all other servers in the farm should be version 1.1 or later. Version 1.0 servers can be included in a UNIX-only farm provided the master browser is version 1.1; however, applications on version 1.0 servers will not be visible through NFuse. All UNIX servers in the farm must participate in the same authentication domain, and it is recommended that this is done through NIS. You can use a mixed farm of MetaFrame for UNIX and MetaFrame for NT servers if you set up your servers so that: The MetaFrame for UNIX servers are all version 1.1 or above, and The MetaFrame for NT servers are all version 1.8 or above. The Citrix XML Service for UNIX requires NFuse Web Extensions version 1.5 or later. In addition, each user requires a Web browser and ICA Client, as required by the NFuse Web Extensions. Installing the Citrix XML Service Installation Overview You need to perform the following steps to install the Citrix XML Service: 1. Create an NFuse administrator user. 2. Login to the server as root 3. Install the Citrix XML Service using pkgadd. 4. Login to the server as a Citrix server Administrator. 5. Start the Citrix XML Service on the server. 6. Configure applications for use with NFuse. The following sections describe the installation process in more detail. Important You must have set up your MetaFrame for UNIX server before installing the Citrix XML Service. See the MetaFrame for UNIX administrators guide for more information.

Installing the Citrix XML Service Chapter 1 Using the Citrix XML Service 5 To install the Citrix XML Service 1. Create a ctxnfuse user as a member of the ctxadm group. 2. Log on as root at the server on which you want to install the Citrix XML Service. 3. If necessary, uncompress the downloaded file, and unpack it with the commands: uncompress name.tar.z tar -xvf name.tar where name is the name of the downloaded file. 4. Copy the Citrix XML service package to an appropriate directory on the server. 5. Change to the directory containing the Citrix XML Service package. 6. Type: pkgadd -d name where name is the name of the package, CTXSxml.i386 for Solaris Intel and CTXSxml.sparc for Solaris SPARC versions. This starts the package installation script. 7. The prompt displays the available packages; for example: The following packages are available: 1 CTXSxml Citrix XML Service for UNIX (r) (i386) 1.0 Select package(s) you wish to process (or 'all' to process all packages). (default: all) [?,??,q]: Press ENTER to install the package. 8. The following prompt is displayed: Enter the location to install the package (default: /opt) : Press ENTER to install in the default location, or specify an alternative location. 9. The following prompt is displayed: Enter the location to install the configuration file (default:/var): Press ENTER to select the default location for the configuration file, or enter an alternative location. 10. The following prompt is displayed: Should the man pages for this package be installed [y,n]? Type y to install the manual pages.

6 Citrix XML Service for UNIX Administrator s Guide 11. The following prompt is displayed: The following files are being installed with setuid and/or setgid permissions: /opt/ctxsxml/lib/ctxxmld <setuid root setgid ctxadm> Do you want to install these as setuid/setgid files [y,n,?,q] Type y to proceed with the installation. 12. The following warning is displayed: This package contains scripts which will be executed with super-user permission during the process of installing this package. Do you want to continue with the installation of <CTXSxml> [y,n,?] Type y to proceed with the installation. pkgadd will then display a list of the files being installed, and if the installation was successful the following text will be displayed: IMPORTANT NOTICE: This version of the XML Service will only operate with version 1.5 (or better) of the NFuse web extensions. Installation of <CTXSxml> was successful. Configuring the Server Port By default the Citrix XML Service is configured to use port 80 to communicate with the NFuse Citrix Web Server Extension. If this is already in use on the server running the Citrix XML Service you should assign it to an unused port. Note The Citrix XML Service port number must be unique; results will be unpredictable if the port is already in use by another process. The NFuse Citrix Web Server Extension should be configured to use the same port number as you have specified for the Citrix XML Service. To configure the Citrix XML Service port Type: ctxnfusesrv -port portnumber where portnumber is an unused port; for example, 8080. Note The Citrix XML Service does not use the new port until it is restarted. You can display the current port number with the following command: ctxnfusesrv -l

Starting the Citrix XML Service Chapter 1 Using the Citrix XML Service 7 When installation is complete you can start the Citrix XML Service on each server using the ctxsrv command. Note The Citrix XML Service is started and stopped automatically with MetaFrame. Starting a MetaFrame server will set off an election, and the master browser may change. The master browser takes some time to acquire information about applications available on the farm. If the Citrix XML Service is started at the same time as a MetaFrame server, it can take up to 10 minutes before these applications are visible through NFuse. To start the Citrix XML Service 1. Log on to the MetaFrame server as a Citrix server Administrator (for example, the default user ctxsrvr). 2. At the command prompt, type: ctxsrv start nfuse Publishing Applications When you start the Citrix XML Service for the first time, application filtering is disabled, so all applications published on the MetaFrame for UNIX server will be visible to all users. This initial configuration is useful for setting up and testing Web pages on the NFuse Citrix Web Server Extension, but once you have configured the Web pages you want to use you will probably want to enable application filtering, and then define the visibility of each application independently. For more information see Chapter 2, Configuring applications. Note For applications to be visible they must have been published by MetaFrame. Configuring the Citrix Web Server Extension The next step is to create customised Web pages for use with the Citrix Web Server Extension. For examples of how to do this using Microsoft s Active Server Pages, Sun Microsystems Java Server Pages, and sites based on Citrix s own extensions to HTML, see the sample Web pages supplied with the Citrix Web Server Extension. Note These are designed for use with the Citrix XML Service for NT, and will need to be modified for use with the Citrix XML Service for UNIX, as described in the section Guidelines for Creating Web Pages for use with NFuse for UNIX below.

8 Citrix XML Service for UNIX Administrator s Guide Stopping the Citrix XML Service 1. Log on to the MetaFrame server as a Citrix server Administrator 2. At the command prompt, type: ctxsrv stop nfuse Guidelines for Creating Web Pages for use with NFuse for UNIX Web pages provided with the Citrix Web Server Extension need to be adapted for use with the UNIX version of NFuse, and this section provides some guidelines for doing this. If accessing a UNIX-only farm, you can either use the Windows wizard to generate pages, or use the example Web pages as a starting point. If you are accessing a UNIX/NT mixed farm, use the multi-farm example Web pages as a starting point. Using the Web Site Wizard If using the Web Site Wizard, note the following points: Do not enable SSL support or ticketing, as these are not currently supported on UNIX. If allowing explicit logins, select 'Force domain', entering the domain value 'unix'. If allowing guest logins, enter the value 'unix' in the domain box. Using the Example Web Pages If using the example Web pages as a starting point, note the following points: Do not use the examples for ticket-based credentials, application filtering by folder, or application filtering by group, as these features are not currently supported on UNIX. Cutomise the login page to handle login without a domain prompt, for example, by replacing: <tr> <td ALIGN=RIGHT VALIGN=CENTER>Domain:</td> <td><input NAME="NFuse_Domain"></td> </tr> with: <INPUT TYPE="hidden" NAME="NFuse_Domain" VALUE="unix">

9 CHAPTER 2 Configuring Applications 2 Overview This chapter describes how to use the Citrix XML Service command-line utilities to configure how published applications are displayed, and to determine the visibility of applications to users. This chapter includes the following topics: Configuring how applications are displayed. Configuring the visibility of applications to users. Refreshing the configuration automatically. Sharing the configuration between servers.

10 Citrix XML Service for UNIX Administrator s Guide Configuring Application Settings When you first install the Citrix XML Service on a MetaFrame server, all published applications have the following settings: Applications have no description, an empty folder name, the ICA icon, and a 640 x 480 16-color window. Filtering is disabled, so all published applications are visible to all users. You can override these settings using the Citrix XML Service command-line utilities. For each application you can individually specify: How it is displayed. For which users or groups it is visible. You can also change the settings that applications have by default. Note The command-line utilities only affect the local Citrix XML Service. If more than one Citrix XML Service for UNIX is running on a server farm, each Citrix XML Service is controlled by its own configuration file. For more information about configuring multiple servers refer to Managing Backup Servers on page 14. An overview of the procedure for configuring applications is as follows: For each application execute a configuration command to specify the appearance and access settings for that application. Execute a refresh command to prompt the service to refresh its configuration from the configuration file. Alternatively, the configuration commands can be submitted from a shell script, in which case the refresh command will typically be included as the last command in the file. These procedures are described in greater detail in the following sections. Note Although you can configure applications that have not been published by MetaFrame, they will only become visible once they have been published.

Configuring how Applications are Displayed Chapter 2 Configuring Applications 11 The following table summarizes the application settings you can configure with the Citrix XML Service command-line configuration utility, ctxnfusecfg: Parameter Description Default -c Number of colors used to display the application. 16 - description An optional description that can be displayed on the users Web page. It should be quoted if it includes spaces. blank -i Specifies an icon file. ICA icon. -f Specifies a folder for the program. blank -w Specifies the window size and type. 640x480 pixels. To configure the appearance settings for an application Give the command: ctxnfusecfg -name applicationname -i iconfile -f foldername -description description -w window -c {16 256} where: applicationname is the MetaFrame application name. iconfile is an xpm file. foldername specifies a folder name. The folder acts as a logical location for the application. In typical usage, you can configure the Citrix Web Server Extension to organize applications into folders. window is: width height percentage percent fullscreen seamless Note The Citrix Web Server Extension is configured by default to launch applications in a seamless window, in which case the -w option will only affect applications if seamless is not available. Alternatively the Citrix Web Server Extension can be configured so the -w option is always used; see the Citrix Web Server Extension documentation. To specify default appearance settings Give the command: ctxnfusecfg -default -i iconfile -f foldername -description description -w window -c {16 256} Any settings not explicity specified for an application will take the default values.

12 Citrix XML Service for UNIX Administrator s Guide To refresh the Citrix XML Service configuration from the configuration file Give the following command: ctxnfuserefresh -cfg Configuring the Visibility of Applications to Users For each application the Citrix XML Service stores a list of groups and users for whom the application is visible. The Citrix XML Service for UNIX uses the same users and groups as MetaFrame for UNIX and the underlying UNIX operating system.you can add groups or users to this list using -gadd and -uadd commands. The -gadd -all command is equivalent to adding all the groups existing at the time the command is executed. The -grm and -urm commands allow you to remove group or users that already have been added. To add or remove users or groups Give the command: ctxnfusecfg -name applicationname -uadd users -urm {-all users} -gadd {-all groups} -grm {-all groups} To refresh the Citrix XML Service configuration from the configuration file Give the following command: ctxnfuserefresh -cfg To refresh the expansion of groups into users The set of users belonging to each group is read when the Citrix XML Service is first run. If you have changed the membership of one or more groups, this command allows you to update the visibility of applications to reflect the changes. Give the following command: ctxnfuserefresh -users If you are making frequent changes to the definitions of the groups on your system and you want the Citrix XML Service to reflect these changes, it is recommended you include the refresh command in a cron style job set to run on a regular basis, such as every 30 minutes.

Chapter 2 Configuring Applications 13 Examples of Configuring the Visibility of Applications To make an application visible to groups and users The following command makes the application Word visible to all users in the group publishing, and to user Smith: ctxnfusecfg -name word -gadd publishing -uadd smith To deny a user access The following command denies user Smith access to the application Word, assuming the user was previously given access with a -uadd smith command: ctxnfusecfg -name word -urm smith Note This does not work if Smith is a member of a group added with -gadd. To exclude visibility to a particular group The following example makes the application xcad available to all groups, excluding the group sales, but including user Jones: ctxnfusecfg -name xcad -gadd -all -grm sales -uadd jones Enabling or Disabling Filtering When the Citrix XML Service is first installed filtering is disabled, so that all published applications are visible to all users irrespective of the effect of ctxnfusecfg commands. To enable application filtering Give the command: ctxnfusefilter -on To list the status of application filtering Give the command: ctxnfusefilter -l To list the application appearance and access settings 1. Give the command: ctxnfusecfg { name applicationname -default} -lacfgiuw

14 Citrix XML Service for UNIX Administrator s Guide The following table gives the effect of each of the parameters: Parameter Checking Application Visibility If applications do not become visible, check for problems with the master browser. You can verify which applications have been published with the MetaFrame command: ctxqserver -app Description l Lists the name and description of the configured application. la lc lf lg li lu -lw Lists all configuration data. Lists the application name and color setting. Lists the application name and folder. Lists the application name and its groups. Outputs the application icon to a file applicationame.xpm. Lists the application name and its users. Lists the application window settings. Managing Backup Servers Note If you change published application information, you may need to wait up to 10 minutes for the Citrix XML Service to obtain an updated list from the master browser. If you have a server farm of UNIX MetaFrame servers you may wish to run the Citrix XML Service on two or more servers to act as backups, allowing applications to be published via the Web even if the main server is unavailable. Note The back-up servers must use the same port setting as the master server. The configuration file should reside on a local disk on the master XML server, and configuration changes should only be made on this server. The back-up server can either copy the master configuration file, or access it via NFS. The back-up servers should run a cron style job to periodically refresh the local configuration. Note The configuration file should not be copied while running ctxnfusecfg. The configuration file has the name ctxxmld.cfg and is installed in the /var/ctxsxml directory by default.

15 CHAPTER 3 Citrix XML Service Command Reference 3 Overview This appendix describes the Citrix XML Service command line utilities. The commandslistedinthissectionare: ctxnfusecfg ctxnfuserefresh ctxnfusefilter ctxnfusesrv Configures the application appearance settings and access settings, or lists the current configuration. Refreshs the Citrix XML Service configuration from the configuration file, or the user account information. Enables or disables application filtering or list the current setting. Configures or lists the Citrix XML Service http port.

16 Citrix XML Service for UNIX Administrator s Guide ctxnfusecfg Description ctxnfusecfg configures the appearance and access settings for an application, sets the default appearance settings for all applications, or lists the current configuration. Configuring an application Syntax ctxnfusecfg -name applicationname [ -i icon file ] [ -f folder name ] [ -description description ] [ -w width height ] [ -w percentage percent ] [ -w fullscreen ] [ -w seamless ] [ -c 16 ] [ -c 256 ] [ -uadd user... ] [ -urm user... ] [ -urm -all ] [ -gadd group... ] [ -gadd -all ] [ -grm user... ] [ -grm -all ] Resetting the configuration Syntax ctxnfusecfg -name applicationname -reset Resetting the configuration of an application restores the default settings and prevents it from being displayed if application filtering is enabled. Listing the configuration Syntax ctxnfusecfg -name applicationname -lacfgiuw

Setting the default configuration Syntax Chapter 3 Citrix XML Service Command Reference 17 ctxnfusecfg -default [ -i icon file ] [ -f folder name ] [ -description description ] [ -w width height] [ -w percentage percent] [ -w fullscreen ] [ -w seamless ] [ -c 16 ] [ -c 256 ] [ -reset ] [ -lacifguw ] Resetting the default configuration Syntax ctxnfusecfg -default -reset Listing the default configuration Syntax ctxnfusecfg -default -lacfiw Options -i iconfile Sets the application s icon. The icon is read from the supplied XPM file. -f foldername Specifies a folder for the application. -description description Sets the application description. The description must be in "quotes" if it consists of more than one word. -w width height Sets the application window width and height. -w percentage percent Sets the application window size to be a percentage of the desktop size. -w fullscreen Sets the application to run in a fullscreen window. -w seamless Sets the application to a seamless window.

18 Citrix XML Service for UNIX Administrator s Guide -c {16 256} Configures the application to use 16 or 256 colors. Options -uadd user -urm user... -urm -all -gadd group... -gadd -all -grm group... -grm -all -reset -lacifguw Adds the specified user(s) to the list of users who can see this application. Removes the specified user(s) from the list of users who can see this application. Removes all users from the list of the users who can see this application. Adds the specified group(s) to the list of groups whose members can see this application. Adds all the list of group(s) currently defined in the NIS domain to the groups whose members can see this application. Removes the specified list of group(s) from the groups whose members can see this application. Removes all the list of group(s) currently defined in the NIS domain from the groups whose members can see this application. Resets the application to its default settings. Displays application settings, where: l =Name a =All c =Colors i = Icon (the icon is saved to a file) f = Folder g = Groups u =Users w = Window settings Remarks Giving the command ctxnfusecfg -l lists details of all the applications currently configured. The commands will not take effect until an ctxnfuserefresh -cfg command is run. You must be a Citrix server administrator to run this command.

ctxnfuserefresh Description ctxnfuserefresh refreshes: Chapter 3 Citrix XML Service Command Reference 19 The Citrix XML Service settings from the configuration file, or: The Citrix XML Services s knowledge of users and groups from the NIS database. Syntax ctxnfuserefresh {-users -cfg} Options -users -cfg Prompts the service to refresh the user and group account data. Prompts the service to refresh configuration from the file. ctxnfusefilter Remarks You must be a Citrix server administrator to run this command. Description ctxnfusefilter lists or configures whether application filtering is to be done. Syntax ctxnfusefilter {-on -off -l} Options -off -on Specifies all applications are visible by all users. Specifies applications are to be filtered by user. -l Lists the appropriate data setting. Remarks You must be a Citrix server administrator to run this command.

20 Citrix XML Service for UNIX Administrator s Guide ctxnfusesrv Description ctxnfusesrv lists or configures the server listening port. Syntax ctxnfusesrv { l port portnumber} Options port portnumber Configures the HTTP server listening port. Parameters portnumber Port number. Remarks You must be a Citrix server administrator to run this command. The default port number is 80.