C H A P T E R  4

Commands

SGD includes a built-in command set for controlling and configuring SGD. This chapter describes the available SGD commands and includes usage examples for each of the commands.

This chapter includes the following topics:


The tarantella command

You can control SGD from the command line using the /install‐dir/bin/tarantella command.

Syntax

tarantella option [ option-specific-arguments ]

Naming Objects on the Command Line

Many of the SGD commands require you to name the objects that they configure. In many cases, you can name objects from different parts of the datastore, such as the local repository or an LDAP directory server.

How you name an object on the command line varies, depending on which part of the SGD datastore the object is from.

For example, an object in the local repository might have this name:

.../_ens/o=Indigo Insurance/ou=Marketing/cn=Cust-o-Dat

For objects in the local repository, the .../_ens part of the name is optional. You can also type the following:

o=Indigo Insurance/ou=Marketing/cn=Cust-o-Dat

An object stored on an LDAP directory server might have this name:

.../_service/sco/tta/ldapcache/cn=Cust-o-Dat,ou=Marketing,o=Indigo Insurance

A server on the network might have this name:

.../_dns/verona.indigo-insurance.com

Description

Do not try to control the SGD server by running binaries directly, or by using kill. Using the tarantella command is the only supported way of controlling the SGD server.

The options for this command enable you to control the SGD server in different ways, or produce information about the SGD server. The tarantella command can be used in your own shell scripts to help automate your administration of SGD.

If the SGD server is running, most tarantella options can be run by root or any user in the ttaserv group. The ttaserv group does not have to be the user’s primary or effective group. See the table below for details of which users can use the command options.

If the SGD server is stopped, only root can use the tarantella command.

The following table shows the available options for this command.


Option Description Can Be Run By More Information
archive Archives the SGD server’s log files. root The tarantella archive command
array Creates and manages arrays of SGD servers. SGD Administrators The tarantella array command
cache Manages the cache of LDAP data. SGD Administrators The tarantella cache command
config Edits global and server-specific configuration. root or ttaserv group The tarantella config command
emulatorsession Lists and controls application sessions. root or ttaserv group The tarantella emulatorsession command
help Shows a list of SGD commands. root or ttaserv group The tarantella help command
license Adds, lists and removes SGD license keys. root or ttaserv group The tarantella license command
object Manipulates objects in the organizational hierarchy. root or ttaserv group The tarantella object command
passcache Manipulates the password cache. root or ttaserv group The tarantella passcache command
print Controls SGD printing services. root or ttaserv group The tarantella print command
query Examines the SGD server’s log files. root The tarantella query command
restart Restarts SGD services. root The tarantella restart command
role Gives people specific roles, and gives them webtop links specific to that role. root or ttaserv group The tarantella role command
security Controls security services, manages certificates. root The tarantella security command
setup Changes Setup options, restores original objects. root The tarantella setup command
start Starts SGD services. root The tarantella start command
start_cdm Starts client drive mapping services. root The tarantella start cdm command
status Shows the current status of SGD servers in the array. root or ttaserv group The tarantella status command
stop Stops SGD services. root The tarantella stop command
stop_cdm Stops client drive mapping services. root The tarantella stop cdm command
tokencache Manipulates the token cache. root or ttaserv group The tarantella tokencache command
tscal Manages Microsoft Windows Terminal Services Client Access Licenses (CALs) for non-Windows clients. root or ttaserv group The tarantella tscal command
uninstall Uninstalls SGD. root The tarantella uninstall command
version Displays versions of installed SGD packages. root or ttaserv group The tarantella version command
webserver Controls the SGD Web Server. root The tarantella webserver command
webtopsession Lists and controls user sessions. root or ttaserv group The tarantella webtopsession command



Note - All commands include a --help option. You can use tarantella command --help to get help on a specific command.



Examples

The following example stops and then restarts the SGD server, without displaying any messages.

tarantella restart --quiet

The following example adds a link for the Write-o-Win application to the webtops of members of the Global Administrators role.

tarantella role add_link --role global \
  --link "o=applications/cn=Write-o-Win"


The tarantella archive command

Archives the SGD server’s log files.

Syntax

tarantella archive

Description

Archiving the logs compresses the files and moves them to a numbered subdirectory of the /install-dir/log directory. A file summary.txt in this directory contains the results of performing the tarantella query command at the time of the archive.

Examples

The following example archives the SGD server’s log files.

tarantella archive


The tarantella array command

This command enables SGD Administrators to set up and dismantle arrays of SGD servers.

The command can be run on any SGD server in the array.

Syntax

tarantella array join | detach | make_primary | list

Description

The following table shows the available subcommands for this command.


Subcommand Description More Information
join Adds a server to an array. tarantella array join
detach Removes secondary servers from an array. tarantella array detach
make_primary Makes a secondary server the primary server for the array that it is currently a member of. tarantella array make_primary
list Lists the members of the array, identifying the primary server. tarantella array list



Note - All commands include a --help option. You can use tarantella array command --help to get help on a specific command.



Examples

The following example adds the server boston to the array with primary server newyork.

tarantella array join \
  --primary newyork.indigo-insurance.com \
  --secondary boston.indigo-insurance.com

The following example makes the secondary server boston the primary server in the array. The previous primary server becomes a secondary server.

tarantella array make_primary \
  --secondary boston.indigo-insurance.com

tarantella array detach

Removes a secondary server from the array of SGD servers it belongs to.

Syntax

tarantella array detach --secondary serv

Description

The following table shows the available options for this command.


Option Description
--secondary Specifies the peer DNS name of a secondary server to remove. The server name must be the name of a secondary server in the same array.

You can only remove one server at a time.


To remove the primary server from an array, first use tarantella array make_primary to make another server the primary server and then detach the old primary server.

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



Note - After running this command, it is advisable to wait until SGD has copied the changes to all SGD servers in the array before running any further tarantella array commands. This is complete when the tarantella status command returns the same result for each SGD server in the array.



If you are using secure intra-array communication, the secondary server generates its own Certificate Authority (CA) certificate and its own server peer certificate when it is detached.

Examples

The following example removes the secondary server boston from the array.

tarantella array detach --secondary boston.indigo-insurance.com

tarantella array join

Adds a server to an array of SGD servers, either as a primary or a secondary server.

Syntax

tarantella array join [ --primary pserv ]
                      [ --secondary sserv ]

Description

The following table shows the available options for this command.


Option Description
--primary Specifies the peer DNS name of the primary server in the array. Defaults to the server where the command is run.
--secondary Specifies the peer DNS name of the server to add. The secondary server must be the only member of an array (a “standalone” server). Defaults to the server where the command is run.

You can only add one secondary server at a time.




Note - After running this command, it is advisable to wait until SGD has copied the changes to all SGD servers in the array before running any further tarantella array commands. This is complete when the tarantella status command returns the same result for each SGD server in the array.



If the server you add has been load balancing application servers using Advanced Load Management, use the tarantella restart --warm command to do a warm restart of the new server after it has joined the array. If the array to which the new server is joined is using Advanced Load Management, do a warm restart of the whole array after the new server has joined.

If you are using secure intra-array communication, you are prompted to accept the CA certificate of either the primary server or the secondary server, depending on where you ran the command.

Examples

The following example adds the server boston to the array with newyork as its primary server.

tarantella array join \
  --primary newyork.indigo-insurance.com \
  --secondary boston.indigo-insurance.com

The following example adds the server where the command is run to the array with newyork as its primary server.

tarantella array join \
  --primary newyork.indigo-insurance.com

tarantella array list

Lists each member of the array of SGD servers, identifying the primary server.



Note - You must be root to run this command.



Syntax

tarantella array list

Examples

The following example lists all SGD servers in the array.

tarantella array list

tarantella array make_primary

Makes a secondary server the primary server for the array that it is currently a member of. The previous primary server becomes a secondary server.

Syntax

tarantella array make_primary --secondary serv

Description

The following table shows the available options for this command.


Subcommand Description
--secondary Specifies the peer DNS name of the secondary server to be made the primary server.



Note - After running this command, it is advisable to wait until SGD has copied the changes to all SGD servers in the array before running any further tarantella array commands. This is complete when the tarantella status command returns the same result for each SGD server in the array.



If you are using secure intra-array communication, the new primary becomes the certificate authority for the array and issues new server peer certificates to all SGD servers in the array.

Examples

The following example makes the secondary server boston the primary server in the array.

tarantella array make_primary \
  --secondary boston.indigo-insurance.com


The tarantella cache command

Flushes the cache of data obtained from an LDAP directory server.

Syntax

tarantella cache --flush ldapgroups|ldapconn|ldapconn‐lookups|krb5config|all

Description

This command flushes the cache of data obtained from an LDAP directory server. This data is only obtained if you are using the following:

The following table shows the values you can use with the --flush option.


Value Description
ldapgroups Flushes the cache of all LDAP group data. Used for Directory Services Integration.
ldapconn Flushes the cache of all the IP address, domain and attribute data.
ldapconn-lookups Flushes the cache of all LDAP search data. Used for Directory Services Integration.
krb5config Refreshes the current Kerberos configuration settings with the original Kerberos configuration of the SGD server. Can be used to reconfigure Kerberos settings without restarting the SGD server. Used for Active Directory authentication only.
all Flushes all LDAP data.



Note - This command only flushes the cache on the SGD server where the command is run.



Examples

The following example flushes the cache of all LDAP data.

tarantella cache --flush all


The tarantella config command

The tarantella config command lists and configures global settings, and also server-specific settings for any SGD server in the array.

Syntax

tarantella config list | edit

Description

The following table shows the available subcommands for this command.


Subcommand Description More Information
list Lists global and server-specific attributes and their current values. tarantella config list
edit Edits global and server-specific attributes. tarantella config edit



Note - All commands include a --help option. You can use tarantella config subcommand --help to get help on a specific command.



Examples

The following example lists server-specific attributes from the server newyork.indigo-insurance.com.

tarantella config list --server newyork.indigo-insurance.com

The following example sets the cpe-maxsessions attribute to 10 for the server where the command is run.

tarantella config edit --cpe-maxsessions 10

tarantella config edit

Edits global and server-specific attributes.

Syntax

tarantella config edit { { --setting
value... }...
                         [ --array | --server serv... ]
                       } | --file file

Description

The following table shows the available options for this command.


Option Description
--setting value... Names an attribute you want to edit, and its new value or values.
--array When configuring a server-specific attribute, applies the change to all SGD servers in the array.
--server When configuring a server-specific attribute, applies the change to each named serv in the array. Use a peer DNS name or IP address for each server.
--file Specifies a file containing a batch of commands to edit attributes.

If neither --array nor --server is specified, the command sets server-specific attributes for the SGD server where the command is run.

Use tarantella config list to see a list of settings you can change.

For detailed information on global attributes, see Chapter 1.

For detailed information on server-specific attributes, see Chapter 2.

Examples

The following example sets the cpe-exitafter attribute to 50 on SGD servers newyork.indigo-insurance.com and boston.indigo-insurance.com.

tarantella config edit \
  --cpe-exitafter 50 \
  --server newyork.indigo-insurance.com \
           boston.indigo-insurance.com

The following example sets the cpe-maxsessions attribute to 10 for the server where the command is run.

tarantella config edit \
  --cpe-maxsessions 10

tarantella config list

Lists global and server-specific attributes and their current values.

Syntax

tarantella config list { [ --setting... ]
                         [ --server serv ]
                       } | --file file

Description

The following table shows the available options for this command.


Option Description
--setting Names an attribute you want to list the value of. If no --setting is specified, all global and server-specific attributes are listed.
--server Lists server-specific attributes for the specified SGD server in the array (use a peer DNS name or IP address). If omitted, lists server-specific attributes for the SGD server where the command is run.
--file Specifies a file containing a batch of commands to list attributes.

For detailed information on global attributes, see Chapter 1.

For detailed information on server-specific attributes, see Chapter 2.

Examples

The following example lists global attributes, and server-specific attributes for the server newyork.indigo-insurance.com.

tarantella config list --server newyork.indigo-insurance.com

The following example lists the value of the array-port-unencrypted attribute.

tarantella config list --array-port-unencrypted


The tarantella emulatorsession command

This command enables SGD Administrators to list and manipulate application sessions.

Syntax

tarantella emulatorsession list | info | shadow | suspend | end

Description

The following table shows the available subcommands for this command.


Subcommand Description More Information
list Lists application sessions. tarantella emulatorsession list
info Displays detailed information about application sessions. tarantella emulatorsession info
shadow Shadows an application session. tarantella emulatorsession shadow
suspend Suspends application sessions. tarantella emulatorsession suspend
end Ends application sessions. tarantella emulatorsession end



Note - All commands include a --help option. You can use tarantella emulatorsession subcommand --help to get help on a specific command.



Examples

The following example lists Emma Rald’s application sessions.

tarantella emulatorsession list \
  --person "o=Indigo Insurance/cn=Emma Rald"

The following example shadows the application session with the specified session ID.

tarantella emulatorsession shadow \
  "paris.indigo-insurance.com:965127448604:...%2f_ens%2fo=Indigo Insurance%2fcn=Emma Rald"

tarantella emulatorsession list

Lists application sessions matching the criteria specified. Information shown includes session IDs, which are used with other tarantella emulatorsession commands.

An example session ID is paris.indigo-insurance.com:965127448604: ...%2f_ens%2fo=Indigo Insurance%2fcn=Emma Rald.

Session IDs can contain spaces, so make sure you quote them.

Syntax

tarantella emulatorsession list 
		[--person pobj]
		[--application appobj]
		[--appserver hobj]
		[--server serv]
		[--format text|count|xml]

Description

The following table shows the available options for this command.


Option Description
--person Lists application sessions matching the person specified. Use the name for the user profile.
--application Lists application sessions matching the application specified. Use the name for the application.
--appserver Lists application sessions matching the application server specified. Use the name for the application server.
--server Lists application sessions hosted by the SGD server specified. Use the name or a peer DNS name for the server.
--full Includes the current IP address of the client and the status of the application session in the output. It takes longer to display this information.
--format Specifies the output format (default setting is text). Use count to display only the number of matching sessions.

If --person, --application, --appserver and --server are all omitted, all application sessions are listed.

Examples

The following example lists Emma Rald’s application sessions.

tarantella emulatorsession list \
  --person "o=Indigo Insurance/cn=Emma Rald"

The following example lists all application sessions hosted by the SGD server boston.indigo-insurance.com. This is the server on which the Protocol Engines run.

tarantella emulatorsession list \
  --server boston.indigo-insurance.com

tarantella emulatorsession info

Displays detailed information about application sessions.

Syntax

tarantella emulatorsession info [ --sessid sessid... ]
				   [ --peid peid... 
				   [--format text|xml|quiet]

Description

The following table shows the available options for this command.


Option Description
--sessid Displays detailed information on application sessions matching the session IDs listed. Use tarantella emulatorsession list to find out session IDs.
--peid Displays detailed information on application sessions matching the Protocol Engine process IDs listed. Valid process IDs are as follows:
  • A number, such as 3456, representing the process ID on the application server where the command is run

  • A combination of peer DNS name and process ID, for example boston.indigo-insurance.com:3456, representing the process ID on the SGD server named.

--format Specifies the output format (the default setting is text). With --format quiet, no messages are displayed.

The exit code indicates the number of session IDs and process IDs named that do not exist.

Examples

The following example displays detailed information on application sessions matching the Protocol Engine process IDs “3456” and “4567” on the application server where the command is run.

tarantella emulatorsession info --peid 3456 4567

tarantella emulatorsession shadow

Shadows an application session, enabling you and the user to interact with the application simultaneously. Only SGD Administrators can shadow application sessions. You can only shadow Windows and X applications. Suspended applications cannot be shadowed.

Syntax

tarantella emulatorsession shadow sessid 
					[--read-only]
					[--silent]
					[--format text|quiet]

Description

The following table shows the available options for this command.


Option Description
sessid Shadows the application session with the specified session ID. Use tarantella emulatorsession list to find out session IDs.
--read-only Enables an Administrator to shadow a session without being able to interact with the application.
--silent Enables an Administrator to shadow a session and interact with the application. The user is not notified that an Administrator wants to shadow their session and they cannot refuse permission.

If this is used with --read-only, the user does not know they are being shadowed and the Administrator cannot interact with the application.

Note - In some countries, it is illegal to shadow a user without their knowledge. It is your responsibility to comply with the law.

--format Specifies the output format (the default setting is text). With --format quiet, no messages are displayed.



Note - You can also shadow a session from the General Settings ⇒ Application Sessions tab of the Administration Console. You select the session from either the user profile object or the application object. However, using the Administration Console does not enable you to shadow a session in read-only mode or silent mode.



If --silent is not used, the user is notified that an Administrator wants to shadow their session and they can refuse permission. The user is also notified when shadowing ends.

The exit code is 0 for success, 1 if the session does not exist, 2 if the session is not shadowable, or 3 if the session is suspended.

Examples

The following example shadows the application session with the specified session ID.

tarantella emulatorsession shadow \
  "paris.indigo-insurance.com:965127448604:...%2f_ens%2fo=Indigo Insurance%2fcn=Emma Rald"

The following example shadows the application session with the specified session ID without the user knowing that they are being shadowed. The Administrator is unable to interact with the application.

tarantella emulatorsession shadow \
  "paris.indigo-insurance.com:965127448604:...%2f_ens%2fo=Indigo Insurance%2fcn=Emma Rald" \
--read-only --silent

tarantella emulatorsession suspend

Suspends application sessions.

Syntax

tarantella emulatorsession suspend sessid...
					[--format text|quiet]

Description

The following table shows available options for this command.


Option Description
sessid... Suspends the application sessions with the specified session IDs. Use tarantella emulatorsession list to find out session IDs.
--format Specifies the output format (the default setting is text). With --format quiet, no messages are displayed.

The exit code is 0 for success, 1 if some sessions do not exist, 2 if some sessions are already suspended, or 3 if there is a mixture of nonexistent and suspended sessions.

Examples

The following example suspends the application session with the specified session ID.

tarantella emulatorsession suspend \
  "paris.indigo-insurance.com:965127448604:...%2f_ens%2fo=Indigo Insurance%2fcn=Emma Rald"

tarantella emulatorsession end

Ends application sessions. The applications exit immediately, which might result in loss of data for users.

Syntax

tarantella emulatorsession end sessid...
                               [--format text|quiet]

Description

The following table shows the available options for this command.


Option Description
sessid... Specifies the session IDs of the application sessions to end. Use tarantella emulatorsession list to find out session IDs.
--format Specifies the output format (the default setting is text). With --format quiet, no messages are displayed.

The exit code of the command is 0 if all sessions were successfully ended, or 1 if some session IDs did not exist.

Examples

The following example ends the specified application session.

tarantella emulatorsession end \
  "paris.indigo-insurance.com:965127448604:...%2f_ens%2fo=Indigo Insurance%2fcn=Emma Rald"


The tarantella help command

Shows a list of the SGD commands.

Syntax

tarantella help

Description

Shows the list of SGD commands.

To get help on a particular command, use tarantella command --help.

Examples

The following example shows the list of SGD commands.

tarantella help


The tarantella license command

This command adds and removes SGD license keys, and displays license information.

Syntax

tarantella license add | remove | list | status | query | info

Description

The following table shows the available subcommands for this command.


Subcommand Description More Information
add Adds license keys for the array. tarantella license add
remove Removes license keys from the array. tarantella license remove
list Lists license keys currently installed. tarantella license list
status Displays current licensing status. tarantella license status
query Displays information on license usage across the array, including infringements. tarantella license query
info Generates signed license key information. tarantella license info



Note - All commands include a --help option. You can use tarantella license command --help to get help on a specific command.



Examples

The following example displays currently installed license keys for the array.

tarantella license list

The following example adds the license key XXXXX-XXXXX-XXXXX-XXXXX-XXXXX. This is not a valid SGD license key.

tarantella license add XXXXX-XXXXX-XXXXX-XXXXX-XXXXX

tarantella license add

Adds license keys to the SGD array.

Syntax

tarantella license add key...

Description

The following table shows the available options for this command.


Option Description
key... Valid SGD license keys.These are of the form AAAAA-AAAAA-AAAAA-AAAAA-AAAAA (five blocks of five case-insensitive characters in the range A-Z, with blocks separated by hyphens).

Examples

The following example adds the license key XXXXX-XXXXX-XXXXX-XXXXX-XXXXX. This is not a valid SGD license key.

tarantella license add XXXXX-XXXXX-XXXXX-XXXXX-XXXXX

tarantella license info

Generates signed license key information.

Syntax

tarantella license info

Description

The output from this command contains the following:

  • A list of your license keys

  • Information about your array

  • The date and time

  • The version of SGD

  • A digital signature



Note - If you copy the output, make sure you include the BEGIN and END lines.



You must run this command on the primary SGD server.

Examples

The following example generates signed license key information.

tarantella license info

tarantella license list

Lists the license keys currently installed for the array

Syntax

tarantella license list

Description

For details about license keys and licenses, see the Sun Secure Global Desktop Administration Guide.

For summary information, use tarantella license status.

Examples

The following example displays currently installed license keys for the array.

tarantella license list

tarantella license query

Displays information on license usage across the array, including license infringements.

Syntax

tarantella license query [ --now
			| --history [--format text|csv|xml] 
			| --maxusers [--format text|xml] ]

Description

To avoid inconsistencies arising from the replication of data across the array, you must run this command on the primary server in the array.



Note - This command only shows the license usage for the software components that are licensed on a per-user basis.



SGD maintains a history of license usage for 30 samples. A sample is created every day, whenever the server is restarted (warm or cold), and whenever your license keys change (licenses added or removed).

The following table shows the available options for this command.


Option Description
--now Displays information on the current license usage across the array. This is the default if no arguments are specified.
--history Displays recent historical information on license usage across the array.

The license usage information is broken down by sample and software component. For each component, the command displays the following:

  • The number of licenses used.

  • The number of licenses available.

  • The maximum number of users using a component during the sample period (the peak).

Use --format to specify the output format (by default, this is text).

--maxusers Use this option to display the number and the names of users who were consuming a license when license usage peaked in the history (30 samples) kept by SGD.

A user consumes licenses if one of the following applies:

  • They are logged in to SGD.

  • They have a suspended application session.

  • They are within the lease period for a named-user license.

Note - Anonymous or guest users are only listed once.

The output distinguishes between standard and secure connections.

Use --format to specify the output format (by default, this is text).


Information on recent license infringements is also shown whenever an SGD Administrator logs in to SGD.

Examples

The following example displays information on the current license usage across the array.

$ tarantella license query --now
License usage at: Tue Feb 20 12:42:21 GMT 2007
Type                In use / Total
Base                9      / 100
UNIX                9      / 100
Mainframe           0      / 100
Windows             5      / 100
AS/400              0      / 100

The following example displays recent historical information on license usage across the array.

$ tarantella license query --history
2007/02/14 15:45:07:
 - Base       in use:     5 / 100         peak: 15
 - UNIX       in use:     5 / 100         peak: 15
 - Mainframe  in use:     0 / 100         peak: 0
 - Windows    in use:     3 / 100         peak: 12
 - AS/400     in use:     0 / 100         peak: 0
2007/02/15 13:25:53:
 - Base       in use:     9 / 100         peak: 16
 - UNIX       in use:     9 / 100         peak: 16
 - Mainframe  in use:     0 / 100         peak: 0
 - Windows    in use:     5 / 100         peak: 13
 - AS/400     in use:     0 / 100          peak: 0

The following example displays the numbers and names of users who were logged in when license usage last peaked.

$ tarantella license query --maxusers
Maximum number of users logged in: 3
o=Indigo Insurance/ou=IT/cn=Bill Orange
o=Indigo Insurance/ou=IT/cn=Ginger Butcher
o=Indigo Insurance/ou=IT/cn=Rusty Spanner

tarantella license remove

Removes license keys from the SGD array.

Syntax

tarantella license remove key...

Description

If you remove all the license keys, SGD reverts to evaluation mode or expired evaluation mode, depending on how recently you installed SGD. You cannot log in to an SGD server when it is in expired evaluation mode. To license a server when it is in expired evaluation mode, you must either add a valid license key (using tarantella license add) or join the server to an array that is already fully licensed.

The following table shows the available options for this command.


Option Description
key... The license keys to remove.

Examples

The following example removes the license key XXXXX-XXXXX-XXXXX-XXXXX-XXXXX. This is not a valid SGD license key.

tarantella license remove XXXXX-XXXXX-XXXXX-XXXXX-XXXXX

tarantella license status

Displays a summary of the current licensing status for the array.

Syntax

tarantella license status

Description

This command shows the following information.

  • The SGD product you are licensed to use.

  • The current license mode of the array. This is either of the following:

    • Evaluation mode. The end date of the evaluation period is displayed in brackets.

    • Fully licensed.

  • A breakdown by license type of what is licensed. For details about license types, see the Sun Secure Global Desktop Administration Guide.

Examples

The following example displays a summary of the current licensing status for the array.

tarantella license status


The tarantella object command

The tarantella object command enables you to create, list, edit and delete objects in the organizational hierarchy. You can also add and remove webtop links, configure application server load balancing for each application, and add and remove group members.

Syntax

tarantella object add_host | add_link | add_member | delete | edit | 
list_attributes | list_contents | new_3270app | new_5250app | 
new_charapp | new_container | new_dc | new_doc | new_group | 
new_host | new_org | new_orgunit | new_person | new_windowsapp | 
new_xapp | remove_host | remove_link | remove_member | rename | script

Description

The following table shows the available subcommands for this command.


Subcommand Description More Information
add_host Adds application servers to the list of those that can run an application. tarantella object add_host
add_link Adds links to webtops. tarantella object add_link
add_member Adds members to a group. tarantella object add_member
delete Permanently deletes objects from the organizational hierarchy. tarantella object delete
edit Edits attributes for an object. tarantella object edit
list_attributes Lists attributes of an object. tarantella object list_attributes
list_contents Lists the contents of an OU or an organization. tarantella object list_contents
new_3270app Creates 3270 application objects. tarantella object new_3270app
new_5250app Creates 5250 application objects. tarantella object new_5250app
new_charapp Creates character application objects. tarantella object new_charapp
new_container Creates Active Directory container objects. tarantella object new_container
new_dc Creates domain component objects. tarantella object new_dc
new_doc Creates document objects. tarantella object new_doc
new_group Creates group objects. tarantella object new_group
new_host Creates application server objects. tarantella object new_host
new_org Creates organization objects. tarantella object new_org
new_orgunit Creates organizational unit objects. tarantella object new_orgunit
new_person Creates user profile objects. tarantella object new_person
new_windowsapp Creates Windows application objects. tarantella object new_windowsapp
new_xapp Creates X application objects. tarantella object new_xapp
remove_host Removes application servers from those that can run an application. tarantella object remove_host
remove_link Removes links from webtops. tarantella object remove_link
remove_member Removes members from groups. tarantella object remove_member
rename Renames or moves an object. tarantella object rename
script Runs a batch script of object commands. tarantella object script



Note - All commands include a --help option. You can use tarantella object subcommand--help to get help on a specific command.



Examples

The following example lists the objects that belong to the organizational unit Sales.

tarantella object list_contents --name \
"o=Indigo Insurance/ou=Sales"

tarantella object add_host

Adds application servers to the list of those that can run an application, for application server load balancing.

Syntax

tarantella object add_host { --name obj...
                             --host hobj...
                           } | --file file

Description

The following table shows the available options for this command.


Option Description
--name The names of application objects you want to configure load balancing for.
--host The names of application server objects you want to add to the load balancing pool.
--file A file containing a batch of commands to configure application server load balancing.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example adds the application server rome to the load balancing pool for the application Slide-o-Win.

tarantella object add_host \
  --name "o=applications/cn=Slide-o-Win" \
  --host "o=appservers/ou=Sales/cn=rome"

The following example adds the group WinHosts to the load balancing pool for the applications Write-o-Win and Slide-o-Win. Load balancing is performed across all the application servers in WinHosts.

tarantella object add_host \
  --name "o=applications/cn=Write-o-Win" \
         "o=applications/cn=Slide-o-Win" \
  --host "o=applications/cn=WinHosts"

tarantella object add_link

Adds links to webtops.

Syntax

tarantella object add_link { --name obj...
                             --link lobj...
                           } | --file file

Description

The following table shows the available options for this command.


Option Description
--name The names of objects you want to add webtop links for.
--link The names of objects you want to add to the webtop.
--file A file containing a batch of commands to add links to webtops.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example adds the Write-o-Win application to Violet Carson’s webtop.

tarantella object add_link \
  --name "o=Indigo Insurance/ou=Sales/cn=Violet Carson" \
  --link "o=applications/cn=Write-o-Win"

The following example adds the group Applications to the webtops of the organizational units Sales and Marketing. Everyone who inherits webtop content from one of these OUs (for example, they belong to that OU and Inherit Assigned Applications from Parent is selected for their user profile object) sees all the applications in the group on their webtop.

tarantella object add_link \
  --name "o=Indigo Insurance/ou=Sales" \
         "o=Indigo Insurance/ou=Marketing" \
  --link "o=applications/cn=Applications"

tarantella object add_member

Adds objects to groups.

Syntax

tarantella object add_member { --name obj...
                               --member mobj...
                             } | --file file

Description

The following table shows the available options for this command.


Option Description
--name Specifies the names of group objects you want to add members for.
--member Specifies the names of objects you want to add to the groups.
--file Specifies a file containing a batch of commands to add group members.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example adds the Write-o-Win application to the group Applications.

tarantella object add_member \
  --name "o=applications/cn=Applications" \
  --member "o=applications/cn=Write-o-Win"

The following example adds the three application server objects rome, brussels and berlin to the group WinHosts. This group can be added to an application’s Hosting Application Servers Tab (from the command line use tarantella object add_host) to perform load balancing between the application servers.

tarantella object add_member \
  --name "o=appservers/cn=WinHosts" \
  --member "o=appservers/ou=Sales/cn=rome" \
           "o=appservers/cn=brussels" \
           "o=appservers/ou=Marketing/cn=berlin"

tarantella object delete

Permanently deletes objects from the organizational hierarchy.

Syntax

tarantella object delete { --name obj [--children] } | --file file

Description

The following table shows the available options for this command.


Option Description
--name Specifies the name of the object you want to delete.
--children When deleting organizational units, Active Directory containers or domain components, confirms that you want to delete the object and all objects that belong to it, recursively. As a safeguard, it is impossible to delete an organizational unit, Active Directory container or domain component without specifying --children.
--file Specifies a file containing a batch of commands to delete objects.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example removes the user profile object for Violet Carson.

tarantella object delete \
  --name "o=Indigo Insurance/ou=Sales/cn=Violet Carson"

The following example deletes the organizational unit Sales.

tarantella object delete \
  --name "o=Indigo Insurance/ou=Sales" \
  --children

tarantella object edit

Edits the attributes of an object in the organizational hierarchy.

Syntax

tarantella object edit { 
  --name obj 
 {--attribute [value]}...
} | --file file

Description

The following table shows the available options for this command.


Option Description
--name Specifies the name of the object you want to edit the attributes of.
{--attribute [value]}... Specifies the attribute names you want to edit, and their new values. The valid attributes depend on the type of object. See the tarantella object new_object_type documentation for the appropriate list. For example, when editing attributes for an application object you can specify --displayusing to edit the Window Type attribute. If you omit value for an attribute, it is deleted from the object.
--file Specifies a file containing a batch of commands to edit attributes.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example changes the Inherit Assigned Applications from Parent attribute for the organizational unit Sales.

tarantella object edit \
  --name "o=Indigo Insurance/ou=Sales" \
  --inherit false

tarantella object list_attributes

Lists the attributes of an object in the organizational hierarchy.

Syntax

tarantella object list_attributes { 
 --name obj 
[--attribute...]
} | --file file

Description

The following table shows the available options for this command.


Option Description
--name Specifies the name of the object you want to list the attributes of.
{--attribute [value]}... Specifies the attribute names you want to list. The valid attributes depend on the type of object. See the tarantella object new_object_type documentation for the appropriate list. For example, when listing attributes for an application object you can specify --displayusing to edit the Window Type attribute.
--file Specifies a file containing a batch of commands to list attributes.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example lists all attributes for the Sales organizational unit.

tarantella object list_attributes \
  --name "o=Indigo Insurance/ou=Sales"

The following example lists the Email Address and Login attributes for the user profile object for Rusty Spanner.

tarantella object list_attributes \
  --name "o=Indigo Insurance/ou=IT/cn=Rusty Spanner" \
  --email --enabled

tarantella object list_contents

Lists the objects that belong to a particular object in the organizational hierarchy.

Syntax

tarantella object list_contents { --name obj }| --file file

Description

The following table shows the available options for this command.


Option Description
--name Specifies the name of the object you want to list the contents of.
--file Specifies a file containing a batch of commands to list object contents.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example lists all the objects within the organizational unit Sales.

tarantella object list_contents \
  --name "o=Indigo Insurance/ou=Sales"

tarantella object new_3270app

Creates one or more 3270 application objects. See 3270 Application Object.

Syntax

tarantella object new_3270app {
  --name obj
  --width pixels
  --height pixels 
[ --description text ]
[ --args args ]
[ --method rexec|telnet|ssh ]
[ --resumable never|session|always ]
[ --endswhen lastclient|windowmanager|windowmanageralone|nowindows|
loginscript|loginscriptnowindows ]
[ --maxinstances 0|instances ]
[ --displayusing webtop|clientwm|newbrowser|independent|kiosk|
localx ]
[ --maximize true|false ]
[ --scalable true|false ]
[ --icon icon_name ]
[ --hints hint...]
[ --hostname host ]
[ --portnumber tcp ]
[ --3270tnclose 0|1|2|3 ]
[ --3270kt pc|sun4|sun5|hp ]
[ --3270bl 0|1|2|3|4 ]
[ --3270ma true|false ]
[ --3270mb true|false ]
[ --3270si true|false ]
[ --3270fg color ]
[ --3270bg color ]
[ --roottype default|custom ]
[ --rootcolor color ]
[ --compression automatic|on|off ]
[ --execution automatic|inorder|optimized ]
[ --interlaced automatic|on|off ]
[ --accel true|false ]
[ --delayed true|false ]
[ --ldapusers user_dn... ]
[ --ldapgroups group_dn... ]
[ --ldapsearch search_string... ]
[ --env setting... ]
[ --login script ]
[ --winmgr command... ]
[ --resumetimeout mins ]
[ --middlemouse ms ]
[ --windowclose notifyapp|killapp|suspendsession|endsession ]
[ --euro unicode|iso8859-15 ]
[ --dpi monitordpi ]
[ --keepopen true|false ]
[ --lockkeymap true|false ]
[ --share true|false ]
[ --ssharguments args ]
 } | --file file

Description

SGD uses the third-party TeemTalk for Unix emulator for 3270 applications. See the TeemTalk for Unix User's Guide supplied with SGD for details.

The following table shows the available options for this command.


Option Description More Information
--name The common name of the object in the SGD datastore. Name
--width The width of the application, in pixels. Window Size: Width
--height The height of the application, in pixels. Window Size: Height
--description A text description of the object. Comment
--args The command-line arguments to use when starting the application. Arguments for Command
--method The mechanism used by the SGD server to access the application server and start the application. Connection Method
--resumable Resumability behavior for the application. Application Resumability
--endswhen When the application session ends. Session Termination
--maxinstances The maximum number of instances of the application a user can run simultaneously. Number of Sessions
--displayusing How the application is displayed to the user. Window Type
--maximize The initial size of the application. Window Size: Client’s Maximum Size
--scalable Scale the application to fit the window in which it is displayed. Window Size: Scale to Fit Window
--icon Webtop icon for the application. Icon
--hints String containing additional name-value data for the application. Hints
--hostname The 3270 host that runs the application. Server Address
--portnumber The TCP port number used to connect to the 3270 host. Server Port
--3270tnclose Behavior when telnet connection to the 3270 host is closed. Connection Closed Action
--3270kt Layout to use for mapping the keyboard to the terminal being emulated. Keyboard Type
--3270bl Number of “soft button” levels to display. Displayed Soft Buttons
--3270ma Maximizes the emulator window. Window Size: Maximized
--3270mb Enables the application’s menu bar. Menu Bar
--3270si Enables the File and Settings menu items. ‘File’ and ‘Settings’ Menus
--3270fg Text color in the application’s text window. Foreground Color
--3270bg Background color of the application’s text window. Background Color
--roottype Appearance of the root window. Window Color
--rootcolor Color of the root window. Window Color: Custom Color
--compression Whether the AIP compresses commands for transmission. Command Compression
--execution Whether the AIP always executes commands in order, or optimizes commands for performance reasons. Command Execution
--interlaced Enables interlaced image transmission. Interlaced Images
--accel Enables graphics acceleration for the application’s display. Graphics Acceleration
--delayed Enables delayed updates of the application’s display. Delayed Updates
--ldapusers Assigns the application to the specified LDAP users. Assigned User Profiles Tab
--ldapgroups Assigns the application to the specified LDAP groups. Assigned User Profiles Tab
--ldapsearch Assigns the application to the users that match the LDAP search criteria. Assigned User Profiles Tab
--env Environment variable settings needed to run the application. Environment Variables
--login The login script used to start the application. Login Script
--winmgr The Window Manager to use for the application. Window Manager
--resumetimeout Number of minutes the application is resumable for. Application Resumability: Timeout
--middlemouse Timeout for emulating a middle mouse button click using a two-button mouse. Middle Mouse Timeout
--windowclose Effect on application session of closing the main application window. Window Close Action
--euro Keycode mapping required by the application to support the euro character. Euro Character
--dpi Monitor resolution that SGD reports to X applications. Monitor Resolution
--keepopen Keep open the connection used to start the application. Keep Launch Connection Open
--lockkeymap Prevents applications from changing keyboard mappings. Keyboard Map: Locked
--share Enables resource sharing for similar application sessions. Share Resources Between Similar Sessions
--ssharguments Command-line arguments for the ssh client. Connection Method: ssh Arguments
--file Batch file used to create multiple objects within the organizational hierarchy.  

To batch-create multiple objects, use the --file option. Use the other options to create a single object.

Examples

The following example creates a new 3270 application object for the application 3270cat. The emulator connects to the 3270 host warsaw.indigo-insurance.com.

tarantella object new_3270app \
  --name "o=applications/ou=Finance/cn=3270cat" \
  --width 1000  --height 800 \
  --app /3270cat \
  --hostname warsaw.indigo-insurance.com

tarantella object new_5250app

Creates one or more 5250 application objects (see 5250 Application Object).

Syntax

tarantella object new_5250app {
  --name obj
  --width pixels
  --height pixels 
[ --description text ]
[ --args args ]
[ --method telnet|ssh ]
[ --resumable never|session|always ]
[ --endswhen lastclient|windowmanager|windowmanageralone|nowindows|
loginscript|loginscriptnowindows ]
[ --maxinstances 0|instances ]
[ --displayusing webtop|newbrowser|independent]
[ --maximize true|false ]
[ --scalable true|false ]
[ --icon icon_name ]
[ --hints hint...]
[ --hostname host ]
[ --portnumber tcp ]
[ --tnclose 0|1|2|3 ]
[ --kt pc|sun4|sun5|hp ]
[ --bl 0|1|2|3|4 ]
[ --ma true|false ]
[ --mb true|false ]
[ --si true|false ]
[ --fg color ]
[ --bg color ]
[ --roottype default|custom ]
[ --rootcolor color ]
[ --compression automatic|on|off ]
[ --execution automatic|inorder|optimized ]
[ --interlaced automatic|on|off ]
[ --accel true|false ]
[ --delayed true|false ]
[ --ldapusers user_dn... ]
[ --ldapgroups group_dn... ]
[ --ldapsearch search_string... ]
[ --env setting... ]
[ --login script ]
[ --winmgr command... ]
[ --resumetimeout mins ]
[ --middlemouse ms ]
[ --windowclose notifyapp|killapp|suspendsession|endsession ]
[ --euro unicode|iso8859-15 ]
[ --dpi monitordpi ]
[ --keepopen true|false ]
[ --lockkeymap true|false ]
[ --share true|false ]
[ --ssharguments args ]
 } | --file file

Description

SGD uses the third-party TeemTalk for Unix emulator for 5250 applications. See the TeemTalk for Unix User's Guide supplied with SGD for details.

The following table shows the available options for this command.


Option Description More Information
--name The common name of the object in the SGD datastore. Name
--width The width of the application, in pixels. Window Size: Width
--height The height of the application, in pixels. Window Size: Height
--description A text description of the object. Comment
--args The command-line arguments to use when starting the application. Arguments for Command
--method The mechanism used by the SGD server to access the application server and start the application. Connection Method
--resumable Resumability behavior for the application. Application Resumability
--endswhen When the application session ends. Session Termination
--maxinstances The maximum number of instances of the application a user can run simultaneously. Number of Sessions
--displayusing How the application is displayed to the user. Window Type
--maximize The initial size of the application. Window Size: Client’s Maximum Size
--scalable Scale the application to fit the window in which it is displayed. Window Size: Scale to Fit Window
--icon Webtop icon for the application. Icon
--hints String containing additional name-value data for the application. Hints
--hostname The AS/400 host that runs the application. Server Address
--portnumber The TCP port number used to connect to the AS/400 host. Server Port
--tnclose Behavior when telnet connection to the AS/400 host is closed. Connection Closed Action
--kt Layout to use for mapping the keyboard to the terminal being emulated. Keyboard Type
--bl Number of “soft button” levels to display. Displayed Soft Buttons
--ma Maximizes the emulator window. Window Size: Maximized
--mb Enables the application’s menu bar. Menu Bar
--si Enables the File and Settings menu items. ‘File’ and ‘Settings’ Menus
--fg Text color in the application’s text window. Foreground Color
--bg Background color of the application’s text window. Background Color
--roottype Appearance of the root window. Window Color
--rootcolor Color of the root window. Window Color: Custom Color
--compression Whether theAIP compresses commands for transmission. Command Compression
--execution Whether the AIP always executes commands in order, or optimizes commands for performance reasons. Command Execution
--interlaced Enables interlaced image transmission. Interlaced Images
--accel Enables graphics acceleration for the application’s display. Graphics Acceleration
--delayed Enables delayed updates of the application’s display. Delayed Updates
--ldapusers Assigns the application to the specified LDAP users. Assigned User Profiles Tab
--ldapgroups Assigns the application to the specified LDAP groups. Assigned User Profiles Tab
--ldapsearch Assigns the application to the users that match the LDAP search criteria. Assigned User Profiles Tab
--env Environment variable settings needed to run the application. Environment Variables
--login The login script used to start the application. Login Script
--winmgr The Window Manager to use for the application. Window Manager
--resumetimeout Number of minutes the application is resumable for. Application Resumability: Timeout
--middlemouse Timeout for emulating a middle mouse button click using a two-button mouse. Middle Mouse Timeout
--windowclose Effect on application session of closing the main application window. Window Close Action
--euro Keycode mapping required by the application to support the euro character. Euro Character
--dpi Monitor resolution that SGD reports to X applications. Monitor Resolution
--keepopen Keep open the connection used to start the application. Keep Launch Connection Open
--lockkeymap Prevents applications from changing keyboard mappings. Keyboard Map: Locked
--share Enables resource sharing for similar application sessions. Share Resources Between Similar Sessions
--ssharguments Command-line arguments for the ssh client. Connection Method: ssh Arguments
--file Batch file used to create multiple objects within the organizational hierarchy.  

To batch-create multiple objects, use the --file option. Use the other options to create a single object.

Examples

The following example creates a new 5250 application object for the application 5250cat. The emulator runs on the application server prague, and connects to the AS/400 host warsaw.indigo-insurance.com.

tarantella object new_5250app \
  --name "o=applications/ou=Finance/cn=5250cat" \
  --width 400  --height 300 \
  --app /5250cat \
  --appserv "o=appservers/cn=Prague" \
  --hostname warsaw.indigo-insurance.com

tarantella object new_charapp

Creates one or more character application objects (see Character Application Object).

Syntax

tarantella object new_charapp {
   --name obj
   --emulator scocon|vt420|wyse60
   --termtype type
   --width pixels 
   --height pixels 
 [ --description text ]
 [ --app pathname ]
 [ --args args ]
 [ --appserv obj... ]
 [ --method telnet|ssh ]
 [ --resumable never|session|always ]
 [ --maxinstances 0|instances ]
 [ --displayusing webtop|newbrowser|independent|kiosk ]
 [ --maximize true|false ]
 [ --cols cols ]
 [ --lines lines ]
 [ --icon icon_name ]
 [ --hints hint...]
 [ --font courier|helvetica|timesroman ]
 [ --fontsize points ]
 [ --fixedfont true|false ]
 [ --autowrap true|false ]
 [ --cursor off|block|underline ]
 [ --statusline none|indicator|hostmessages|standard|extended ]
 [ --scrollstyle line|multiple|smooth ]
 [ --border normal|indented|raised ]
 [ --answermsg message ]
 [ --appkeymode true|false ]
 [ --keypad numeric|application ]
 [ --cursorkeys application|cursor ]
 [ --escape 7-bit|8-bit ]
 [ --codepage 437|850|852|860|863|865|8859-1|8859-2|Multinational|
 Mazovia|CP852 ]
 [ --ldapusers user_dn... ]
 [ --ldapgroups group_dn... ]
 [ --ldapsearch search_string... ]
 [ --loadbal default|cpu|memory|sessions ]
 [ --compression automatic|on|off ]
 [ --env setting... ]
 [ --login script ]
 [ --keymap keymap ]
 [ --attributemap attrmap ]
 [ --colormap colormap ]
 [ --resumetimeout mins ]
 [ --windowclose suspendsession|endsession ]
 [ --ssharguments args ]
 } | --file file

Description

The following table shows the available options for this command.


Option Description More Information
--name The common name of the object in the SGD datastore. Name
--emulator The type of emulation required for the application. Emulation Type
--termtype The terminal type required for the application. Terminal Type
--width The width of the application, in pixels. Window Size: Width
--height The height of the application, in pixels. Window Size: Height
--description A text description of the object. Comment
--app Full path name of the application. Application Command
--args The command-line arguments to use when starting the application. Arguments for Command
--appserv The application servers that can run the application. Hosting Application Servers Tab
--method The mechanism used by the SGD server to access the application server and start the application. Connection Method
--resumable Resumability behavior for the application. Application Resumability
--maxinstances The maximum number of instances of the application a user can run simultaneously. Number of Sessions
--displayusing How the application is displayed to the user. Window Type
--maximize The initial size of the application. Window Size: Client’s Maximum Size
--cols The number of columns in the terminal window. Window Size: Columns
--lines The number of lines in the terminal window. Window Size: Lines
--icon Webtop icon for the application. Icon
--hints String containing additional name-value data for the application. Hints
--font Determines the font family used within the terminal window for the application Font Family
--fontsize Defines the font size in the terminal window. Font Size
--fixedfont Uses the font size specified by --fontsize for the terminal window. Font Size: Fixed Font Size
--autowrap Determines the behavior when a user types characters extending beyond the right edge of the terminal window. Line Wrapping
--cursor Cursor style used for the application. Cursor
--statusline Specifies the type of status line. Status Line
--scrollstyle The scroll behavior of the terminal window. Scroll Style
--border The border style for the terminal window. Border Style
--answermsg Defines the message to return when an inquiry is sent from the application server to the emulator. Answerback Message
--appkeymode Determines whether the application can change the codes generated by keys on the keyboard. Keyboard Codes Modification
--keypad Specifies the behavior of the cursor keys. Numpad Codes Modification
--cursorkeys Specifies the behavior of the cursor keys. Cursor Key Codes Modification
--escape Specifies how escape sequences are sent from the emulator to the application server. Escape Sequences
--codepage The code page to use for the emulator. Code Page
--ldapusers Assigns the application to the specified LDAP users. Assigned User Profiles Tab
--ldapgroups Assigns the application to the specified LDAP groups. Assigned User Profiles Tab
--ldapsearch Assigns the application to the users that match the LDAP search criteria. Assigned User Profiles Tab
--loadbal Load balancing algorithm to use. Application Load Balancing
--compression Whether the Adaptive Internet Protocol (AIP) compresses commands for transmission. Command Compression
--env Environment variable settings needed to run the application. Environment Variables
--login The login script used to start the application. Login Script
--keymap Path name of a keyboard map file. Keyboard Map
--attributemap The attribute map to use for the application. Attribute Map
--colormap The color map to use for the application. Color Map
--resumetimeout Number of minutes the application is resumable for. Application Resumability: Timeout
--windowclose Effect on application session of closing the main application window. Window Close Action
--ssharguments Command-line arguments for the ssh client. Connection Method: ssh Arguments
--file Batch file used to create multiple objects within the organizational hierarchy.  

To batch-create multiple objects, use the --file option. Use the other options to create a single object.

Examples

The following example creates a character application object for the application Pers‐o-dat. The application can be run on the application servers prague and london. Application server load balancing decides which application server to use.

tarantella object new_charapp \
  --name "o=applications/cn=Pers-o-dat" \
  --emulator vt420 \
  --termtype vt220 \
  --width 400 \
  --height 300 \
  --app /bin/persodat \
  --appserv "o=appservers/cn=prague" \
            "o=appservers/ou=IT/cn=london"

tarantella object new_container

Creates one or more Active Directory container objects (see Directory (Light): Active Directory Container Object).

Syntax

tarantella object new_container { --name obj } | --file file

Description

To batch-create multiple objects, use the --file option. Use the other options to create a single object.

Examples

The following example creates a new Active Directory container object with name Users, within the indigo-insurance.com domain components.

tarantella object new_container \
  --name "dc=com/dc=indigo-insurance/cn=Users"

The following example creates two Active Directory container objects using a batch script defined as a “here-document”. You can alternatively store the batch script in a file, and reference it using --file filename.

tarantella object new_container --file - <<EOF
  --name "dc=com/dc=indigo-insurance/cn=Users"
  --name "dc=com/dc=indigo-insurance/cn=Applications"
EOF

tarantella object new_dc

Creates one or more domain component objects (see Directory (Light): Domain Component Object).

Syntax

tarantella object new_dc { --name obj } | --file file

Description

To batch-create multiple objects, use the --file option. Use the other options to create a single object.

Examples

The following example creates a new domain component object with name com, at the top level of the organizational hierarchy.

tarantella object new_dc \
  --name "dc=com"

The following example creates two domain component objects using a batch script defined as a “here-document”. You can alternatively store the batch script in a file, and reference it using --file filename.

tarantella object new_orgunit --file - <<EOF
  --name "dc=com"
  --name "dc=com/dc=indigo-insurance"
EOF

tarantella object new_doc

Creates one or more document objects (see Document Object).

Syntax

tarantella object new_doc {
   --name obj 
   --url url 
 [ --description text ]
 [ --newbrowser true|false ]
 [ --icon icon_name ]
 [ --hints hint...]
 [ --ldapusers user_dn... ]
 [ --ldapgroups group_dn... ]
 [ --ldapsearch search_string... ]
 } | --file file

Description

The following table shows the available options for this command.


Option Description More Information
--name The name of the document object. Name
--url URL displayed when document object link is clicked. URL
--description A text description of the object. Comment
--newbrowser Displays the document in a new browser window. Window Type: New Browser Window
--icon Webtop icon for the application. Icon
--hints String containing additional name-value data for the application. Hints
--ldapusers Assigns the application to the specified LDAP users. Assigned User Profiles Tab
--ldapgroups Assigns the application to the specified LDAP groups. Assigned User Profiles Tab
--ldapsearch Assigns the application to the users that match the LDAP search criteria. Assigned User Profiles Tab
--file A file containing a batch of commands to configure application server load balancing.  

To batch-create multiple objects, use the --file option. Use the other options to create a single object.

Examples

The following example creates a new document object with common name PhoneList, belonging to the organizational unit applications.

tarantella object new_doc \
  --name "o=Indigo Insurance/ou=Finance/ou=Administration/cn=Phone List" \
  --url http://newyork.indigo-insurance.com \
  --newbrowser false

The following example creates two document objects using a batch script defined as a “here-document”. You can alternatively store the batch script in a file, and reference it using --file filename.

tarantella object new_doc --file - <<EOF
  --name "o=applications/ou=Finance/ou=Administration/cn=Phone List" 
  --url http://newyork.indigo-insurance.com \
  --newbrowser false
  --name "o=applications/cn=Indigo Insurance web site" \
  --url http://www.indigo-insurance.com \
  --newbrowser true
EOF

tarantella object new_group

Creates one or more group objects (see Group Object).

Syntax

tarantella object new_group {
   --name obj 
 [ --description text ]
 [ --member obj... ]
 [ --ldapusers user_dn... ]
 [ --ldapgroups group_dn... ]
 [ --ldapsearch search_string... ]
 } | --file file

Description

The following table shows the available options for this command.


Option Description More Information
--name The name of the group object. Name
--description A text description of the object. Comment
--member Member of the group object. Members Tab
--ldapusers Assigns the application to the specified LDAP users. Assigned User Profiles Tab
--ldapgroups Assigns the application to the specified LDAP groups. Assigned User Profiles Tab
--ldapsearch Assigns the application to the users that match the LDAP search criteria. Assigned User Profiles Tab
--file A file containing a batch of commands to configure application server load balancing.  

To batch-create multiple objects, use the --file option. Use the other options to create a single object.

Examples

The following example creates a new group object with common name WinHosts, belonging to the organization object appservers. The group’s members are the application server objects for the application servers rome, brussels and berlin.

tarantella object new_group \
  --name "o=appservers/cn=WinHosts" \
  --member "o=appservers/ou=Sales/cn=rome" \
           "o=appservers/cn=brussels" \
           "o=appservers/ou=Marketing/cn=berlin"

The following example creates three group objects using a batch script defined as a “here-document”. The groups have no members (use tarantella object add_member to add members later from the command line). You can alternatively store the batch script in a file, and reference it using --file filename.

tarantella object new_group --file - <<EOF
  --name "o=appservers/cn=WinHosts"
  --name "o=appservers/cn=UNIXHosts"
  --name "o=applications/cn=Applications"
EOF

tarantella object new_host

Creates one or more application server objects (see Application Server Object).

Syntax

tarantella object new_host {
   --name obj 
   --address address 
 [ --description text ]
 [ --ntdomain dom ]
 [ --available true|false ]
 [ --auth trytta|nevertrytta|default ]
 [ --location location ]
 [ --hostlocale ll_tt ]
 } | --file file

Description

The following table shows the available options for this command.


Option Description More Information
--name The names of objects you want to add webtop links for. Name
--address Network address of the application server. Address
--description A text description of the object. Comment
--ntdomain The Windows domain used for application server authentication. Domain Name
--available Specifies whether applications can run on this application server. Application Start
--auth Specifies the policy for authenticating users on the application server, if no password is already cached for that server. Password Cache Usage
--location String describing the location of the application server. Used for load balancing. Load Balancing Groups
--hostlocale Default language setting for the application server. Prompt Locale
--file A file containing a batch of commands to add links to webtops.  



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example creates a new application server object with common name paris, belonging to the organizational unit object Finance (which must already exist).

tarantella object new_host \
  --name "o=appservers/ou=Finance/cn=paris" \
  --address paris.indigo-insurance.com \
  --auth default \
  --location Europe-north

The following example creates three application server objects using a batch script defined as a “here-document”. You can alternatively store the batch script in a file, and reference it using --file filename.

tarantella object new_host --file - <<EOF
  --name "o=appservers/ou=Finance/cn=paris" \
  --address paris.indigo-insurance.com
  --name "o=appservers/cn=brussels" \
  --address brussels.indigo-insurance.com
  --name "o=appservers/ou=IT/cn=london" \
  --address london.indigo-insurance.com
EOF

tarantella object new_org

Syntax

Creates one or more organization (O) objects (see Directory: Organization Object).

tarantella object new_org {
   --name obj 
 [ --description text ]
 [ --conntype type_spec... ]
 [ --cdm drive_spec... ]
 [ --userprintingconfig true|false ]
 [ --mapprinters 2|1|0 ]
 [ --pdfenabled 1|0 ]
 [ --pdfviewerenabled 1|0 ]
 [ --pdfdriver driver_name ]
 [ --pdfisdefault 1|0 ]
 [ --pdfviewerisdefault 1|0 ]
 [ --links obj... ]
 [ --editprofile 2|1|0 ] 
 [ --clipboard 2|1|0 ]
 [ --serialport 2|1|0 ] 
 } | --file file

Description

The following table shows the available options for this command.


Option Description More Information
--name The name of the organization object in the SGD datastore. Name
--description A text description of the object. Comment
--conntype The connections that are allowed between the client device and the SGD server. Connections
--cdm The drives on a Microsoft Windows client device that can be accessed from applications running on application servers. Client Drive Mapping
--userprintingconfig Enables user-specific printing configuration. Client Printing: Override
--mapprinters The client printers users can print to when printing from Windows applications. Client Printing
--pdfenabled Enables users to print using the SGD “Universal PDF Printer” printer when printing from Windows applications. Universal PDF Printer
--pdfviewerenabled Enables users to print using the SGD “Universal PDF Viewer” printer when printing from Windows applications. Universal PDF Viewer
--pdfdriver The printer driver to use for SGD PDF printing when printing from Windows applications. Postscript Printer Driver
--pdfisdefault The SGD “Universal PDF Printer” printer as the client’s default printer when printing from Windows applications. Make Universal PDF Printer the Default
--pdfviewerisdefault The SGD “Universal PDF Viewer” printer as the client’s default printer when printing from Windows applications. Make Universal PDF Viewer the Default
--links Defines the content of a webtop. Assigned Applications Tab
--editprofile Whether users can create and edit profiles for use with the SGD Client. Client Profile Editing
--clipboard Whether users can use copy and paste in Windows or X application application sessions. Copy and Paste
--serialport Whether users can access the serial ports on a client device from a Windows application running on a Microsoft Windows Server 2003 application server. Serial Port Mapping
--file Batch file used to create multiple objects within the organizational hierarchy.  

To batch-create multiple objects, use the --file option. Use the other options to create a single object.

Examples

The following example creates a new organization object with name Indigo Insurance. Connections for all users in the organization are secure (SSL-based) unless the OU or user profile objects are configured to give a different type of connection.

tarantella object new_org \
  --name "o=Indigo Insurance" \
  --conntype '*:*:SSL'

The following example creates two organization objects using a batch script defined as a “here-document”. You can alternatively store the batch script in a file, and reference it using --file filename.

tarantella object new_org --file - <<EOF
  --name "o=Indigo Insurance"
  --name "o=Indigo Insurance Services"
EOF

tarantella object new_orgunit

Creates one or more organizational unit (OU) objects (see Directory: Organizational Unit Object).

Syntax

tarantella object new_orgunit {
   --name obj 
 [ --description text ]
 [ --inherit true|false ]
 [ --conntype type_spec... ]
 [ --cdm drive_spec... ]
 [ --userprintingconfig 1|0 ]
 [ --mapprinters 2|1|0 ]
 [ --pdfenabled 1|0 ]
 [ --pdfviewerenabled 1|0 ]
 [ --pdfdriver driver_name ]
 [ --pdfisdefault 1|0 ]
 [ --pdfviewerisdefault 1|0 ] 
 [ --links obj... ]
 [ --editprofile 2|1|0 ]
 [ --clipboard 2|1|0 ]
 [ --serialport 2|1|0 ] 
 } | --file file

Description

The following table shows the available options for this command.


Option Description More Information
--name The name of the organizational unit object in the SGD datastore. Name
--description A text description of the object. Comment
--inherit Whether the webtop content for the object also includes the webtop content for the object’s parent. Inherit Assigned Applications from Parent
--conntype The connections that are allowed between the client device and the SGD server. Connections
--cdm The drives on a Microsoft Windows client device that can be accessed from applications running on application servers. Client Drive Mapping
--userprintingconfig Enables user-specific printing configuration. Client Printing: Override
--mapprinters The client printers users can print to when printing from Windows applications. Client Printing
--pdfenabled Enables users to print using the SGD “Universal PDF Printer” printer when printing from Windows applications. Universal PDF Printer
--pdfviewerenabled Enables users to print using the SGD “Universal PDF Viewer” printer when printing from Windows applications. Universal PDF Viewer
--pdfdriver The printer driver to use for SGD PDF printing when printing from Windows applications. Postscript Printer Driver
--pdfisdefault Sets the SGD “Universal PDF Printer” printer as the client’s default printer when printing from Windows applications. Make Universal PDF Printer the Default
--pdfviewerisdefault Sets the SGD “Universal PDF Viewer” printer as the client’s default printer when printing from Windows applications. Make Universal PDF Viewer the Default
--links Defines the content of a webtop. Assigned Applications Tab
--editprofile Whether users can create and edit profiles for use with the Sun Secure Global Desktop Client. Client Profile Editing
--clipboard Whether users can use copy and paste in Windows or X application application sessions. Copy and Paste
--serialport Whether users can access the serial ports on a client device from a Windows application running on a Microsoft Windows Server 2003 application server. Serial Port Mapping
--file Batch file used to create multiple objects within the organizational hierarchy.  

To batch-create multiple objects, use the --file option. Use the other options to create a single object.

Examples

The following example creates a new OU object with the name IT, belonging to the organization object Indigo Insurance (which must already exist). This OU inherits webtop content from its parent (the organization object). Connections for all users in the OU are secure (SSL-based) unless their user profile objects are configured to give a different type of connection.

tarantella object new_orgunit \
  --name "o=Indigo Insurance/ou=IT" \
  --inherit true \
  --conntype '*:*:SSL'

The following example creates three OU objects using a batch script defined as a “here-document”. The OU Administration belongs to the OU Finance, just created. You can alternatively store the batch script in a file, and reference it using --file filename.

tarantella object new_orgunit --file - <<EOF
  --name "o=Indigo Insurance/ou=IT"
  --name "o=Indigo Insurance/ou=Finance"
  --name "o=Indigo Insurance/ou=Finance/ou=Administration"
EOF

tarantella object new_person

Creates one or more user profile objects (see User Profile Object).

Syntax

tarantella object new_person {
   --name obj 
   --surname surname
 [ --description text ]
 [ --user user ]
 [ --email name@domain ]
 [ --ntdomain dom ]
 [ --inherit true|false ]
 [ --shared true|false ]
 [ --enabled true|false ]
 [ --conntype type_spec... ]
 [ --cdm drive_spec... ]
 [ --keymap keymap ]
 [ --bandwidth limit ]
 [ --links obj... ]
 [ --userprintingconfig 1|0 ]
 [ --mapprinters 2|1|0 ]
 [ --pdfenabled 1|0 ]
 [ --pdfviewerenabled 1|0 ]
 [ --pdfdriver driver_name ]
 [ --pdfisdefault 1|0 ]
 [ --pdfviewerisdefault 1|0 ]
 [ --editprofile 2|1|0 ] 
 [ --clipboard 2|1|0 ]
 [ --serialport 2|1|0 ] 
 } | --file file

Description

The following table shows the available options for this command.


Option Description More Information
--name The common name of the object in the SGD datastore. Name
--surname The surname (family name) for the user profile. Surname
--description A text description of the object. Comment
--user The user name for the user profile. This is typically their UNIX user name. Login Name
--email The email address for the user profile. Email Address
--ntdomain The Windows domain used for application server authentication. Domain Name
--inherit Whether the webtop content for the object also includes the webtop content for the object’s parent. Inherit Assigned Applications from Parent
--shared Whether the user profile object is used by a single user, or can be shared by multiple users in the form of a “guest” account. Login: Multiple
--enabled Whether someone can log in using this user profile object. Login
--conntype Defines the connections that are allowed between the client device and the SGD server. Connections
--cdm The drives on a Microsoft Windows client device that users can access from applications. Client Drive Mapping
--keymap The path name of a keyboard map file. Keyboard Map
--bandwidth The maximum bandwidth this person can use for applications. Bandwidth Limit
--links Defines the content of a webtop. Assigned Applications Tab
--userprintingconfig Enables user-specific printing configuration. Client Printing: Override
--mapprinters The client printers users can print to when printing from Windows applications. Client Printing
--pdfenabled Enables users to print using the SGD “Universal PDF Printer” printer when printing from Windows applications. Universal PDF Printer
--pdfviewerenabled Enables users to print using the SGD “Universal PDF Viewer” printer when printing from Windows applications. Universal PDF Viewer
--pdfdriver The printer driver to use for SGD PDF printing when printing from Windows applications. Postscript Printer Driver
--pdfisdefault Sets the SGD “Universal PDF Printer” printer as the client’s default printer when printing from Windows applications. Make Universal PDF Printer the Default
--pdfviewerisdefault Sets the SGD “Universal PDF Viewer” printer as the client’s default printer when printing from Windows applications. Make Universal PDF Viewer the Default
--editprofile Whether users can create and edit profiles for use with the SGD Client. Client Profile Editing
--clipboard Whether users can use copy and paste in application application sessions. Copy and Paste
--serialport Whether users can access the serial ports on a client device from a Windows application running on a Microsoft Windows Server 2003 application server. Serial Port Mapping
--file Batch file used to create multiple objects within the organizational hierarchy.  

To batch-create multiple objects, use the --file option. Use the other options to create a single object.

Examples

The following example creates a new user profile object for Indigo Jones. Indigo inherits webtop content from the organization object, and is given a secure (SSL‐based) connection.

tarantella object new_person \
  --name "o=Indigo Insurance/cn=Indigo Jones" \
  --surname Jones \
  --user indigo \
  --email indigo@indigo-insurance.com \
  --inherit true \
  --conntype '*:*:SSL'

The following example creates three user profile objects using a batch script defined as a “here-document”. You can alternatively store the batch script in a file, and reference it using --file filename.

tarantella object new_person --file - <<EOF
  --name "o=Indigo Insurance/cn=Indigo Jones" --surname Jones
  --name "o=Indigo Insurance/ou=IT/cn=Bill Orange" --surname Orange
  --name "o=Indigo Insurance/ou=Finance/cn=Mulan Rouge" --surname Rouge
EOF

tarantella object new_windowsapp

Creates one or more Windows application objects (see Windows Application Object).

Syntax

tarantella object new_windowsapp {
   --name obj
   --width pixels
   --height pixels 
 [ --description text ]
 [ --winproto wts|winframe|none ]
 [ --trylocal true|false ]
 [ --ntdomain dom ]
 [ --app pathname ]
 [ --args args ]
 [ --appserv obj... ]
 [ --method rexec|telnet|ssh ]
 [ --resumable never|session|always ]
 [ --endswhen lastclient|windowmanager|windowmanageralone|nowindows|
 loginscript|loginscriptnowindows ]
 [ --maxinstances 0|instances ]
 [ --displayusing webtop|newbrowser|independent|kiosk|localx|
 seamless ]
 [ --maximize true|false ]
 [ --scalable true|false ]
 [ --depth 8|16|24 ]
 [ --icon icon_name ]
 [ --hints hint...]
 [ --clipboardlevel level ]
 [ --roottype default|custom ]
 [ --rootcolor color ]
 [ --compression automatic|on|off ]
 [ --execution automatic|inorder|optimized ]
 [ --interlaced automatic|on|off ]
 [ --accel true|false ]
 [ --delayed true|false ]
 [ --ldapusers user_dn... ]
 [ --ldapgroups group_dn... ]
 [ --ldapsearch search_string... ]
 [ --loadbal default|cpu|memory|sessions ]
 [ --env setting... ]
 [ --login script ]
 [ --winmgr command... ]
 [ --protoargs args ]
 [ --resumetimeout mins ]
 [ --middlemouse ms ]
 [ --windowclose suspendsession|endsession ]
 [ --euro unicode|iso8859-15 ]
 [ --dpi monitordpi ]
 [ --keepopen true|false ]
 [ --lockkeymap true|false ]
 [ --remotewindowkeys true|false ]
 } | --file file

Description

The following table shows the available options for this command.


Option Description More Information
--name The common name of the object in the SGD datastore. Name
--width The width of the application, in pixels. Window Size: Width
--height The height of the application, in pixels. Window Size: Height
--description A text description of the object. Comment
--winproto The protocol used to connect to the server hosting the application. Windows Protocol
--trylocal Try starting the application from the user’s client device. Windows Protocol: Try Running From Client First
--ntdomain The Windows NT domain to use for the application server authentication process. Domain Name
--app Full path name of the application. Application Command
--args The command-line arguments to use when starting the application. Arguments for Command
--appserv The application servers that can run the application. Hosting Application Servers Tab
--method The mechanism used by the SGD server to access the application server and start the application. Connection Method
--resumable Resumability behavior for the application. Application Resumability
--endswhen When the application session ends. Session Termination
--maxinstances The maximum number of instances of the application a user can run simultaneously. Number of Sessions
--displayusing How the application is displayed to the user. Window Type
--maximize The initial size of the application. Window Size: Client’s Maximum Size
--scalable Scale the application to fit the window in which it is displayed. Window Size: Scale to Fit Window
--depth Color depth for the application. Color Depth
--icon Webtop icon for the application. Icon
--hints String containing additional name-value data for the application. Hints
--clipboardlevel Clipboard security level for the application. Copy and Paste: Application’s Clipboard Security Level
--roottype Appearance of the root window. Window Color
--rootcolor Color of the root window. Window Color: Custom Color
--compression Whether the Adaptive Internet Protocol (AIP) compresses commands for transmission. Command Compression
--execution Whether the Adaptive Internet Protocol (AIP) always executes commands in order, or optimizes commands for performance reasons. Command Execution
--interlaced Enables interlaced image transmission. Interlaced Images
--accel Enables graphics acceleration for the application’s display. Graphics Acceleration
--delayed Enables delayed updates of the application’s display. Delayed Updates
--ldapusers Assigns the application to the specified LDAP users. Assigned User Profiles Tab
--ldapgroups Assigns the application to the specified LDAP groups. Assigned User Profiles Tab
--ldapsearch Assigns the application to the users that match the LDAP search criteria. Assigned User Profiles Tab
--loadbal Load balancing algorithm to use. Application Load Balancing
--env Environment variable settings needed to run the application. Environment Variables
-login The login script used to start the application. Login Script
--winmgr The Window Manager to use for the application. Window Manager
--protoargs Command-line arguments used for the Windows Protocol (--winproto). Arguments for Protocol
--resumetimeout Number of minutes the application is resumable for. Application Resumability: Timeout
--middlemouse Timeout for emulating a middle mouse button click using a two-button mouse. Middle Mouse Timeout
--windowclose Effect on application session of closing the main application window. Window Close Action
--euro Keycode mapping required by the application to support the euro character. Euro Character
--dpi Monitor resolution that SGD reports to X applications. Monitor Resolution
--keepopen Keep open the connection used to start the application. Keep Launch Connection Open
--lockkeymap Prevents applications from changing keyboard mappings. Keyboard Map: Locked
--remotewindowkeys Sends window management key strokes to the remote session. Window Management Keys
--file Batch file used to create multiple objects within the organizational hierarchy.  

To batch-create multiple objects, use the --file option. Use the other options to create a single object.

Examples

The following example creates a new Windows application object for the application Write-o-Win. The application runs on the application server rome.

tarantella object new_windowsapp \
  --name "o=applications/cn=Write-o-Win" \
  --width 1000  --height 800 \
  --app c:\\programs\\apps\\write.exe \
  --appserv "o=appservers/ou=Sales/cn=rome" 

tarantella object new_xapp

Creates one or more X application objects (see X Application Object).

Syntax

tarantella object new_xapp {
   --name obj
   --width pixels
   --height pixels 
 [ --description text ]
 [ --app pathname ]
 [ --args args ]
 [ --appserv obj... ]
 [ --method rexec|telnet|ssh ]
 [ --resumable never|session|always ]
 [ --endswhen lastclient|windowmanager|windowmanageralone|nowindows|
loginscript|loginscriptnowindows ]
 [ --maxinstances 0|instances ]
 [ --displayusing webtop|clientwm|newbrowser|independent|kiosk|
localx ]
 [ --maximize true|false ]
 [ --scalable true|false ]
 [ --depth 8|16|24|16/8|24/8|8/16|8/24 ]
 [ --icon icon_name ]
 [ --hints hint...]
 [ --clipboardlevel level ]
 [ --roottype default|custom ]
 [ --rootcolor color ]
 [ --compression automatic|on|off ]
 [ --execution automatic|inorder|optimized ]
 [ --quality automatic|best|24|21|18|16|15|12|9|6 ]
 [ --interlaced automatic|on|off ]
 [ --accel true|false ]
 [ --delayed true|false ]
 [ --ldapusers user_dn... ]
 [ --ldapgroups group_dn... ]
 [ --ldapsearch search_string... ]
 [ --loadbal default|cpu|memory|sessions ]
 [ --env setting... ]
 [ --login script ]
 [ --winmgr command... ]
 [ --resumetimeout mins ]
 [ --middlemouse ms ]
 [ --force3button true|false ]
 [ --windowclose notifyapp|killapp|suspendsession|endsession ]
 [ --euro unicode|iso8859-15 ]
 [ --dpi monitordpi ]
 [ --keepopen true|false ]
 [ --lockkeymap true|false ]
 [ --share true|false ]
 [ --securityextension true|false ]
 [ --ssharguments args ]
 [ --unixaudiopreload true|false ]
 [ --remotewindowkeys true|false ]
 } | --file file

Description

The following table shows the available options for this command.


Option Description More Information
--name The common name of the object in the SGD datastore. Name
--width The width of the application, in pixels. Window Size: Width
--height The height of the application, in pixels. Window Size: Height
--description A text description of the object. Comment
--app Full path name of the application. Application Command
--args The command-line arguments to use when starting the application. Arguments for Command
--appserv The application servers that can run the application. Hosting Application Servers Tab
--method The mechanism used by the SGD server to access the application server and start the application. Connection Method
--resumable Resumability behavior for the application. Application Resumability
--endswhen When the application session ends. Session Termination
--maxinstances The maximum number of instances of the application a user can run simultaneously. Number of Sessions
--displayusing How the application is displayed to the user. Window Type
--maximize The initial size of the application. Window Size: Client’s Maximum Size
--scalable Scale the application to fit the window in which it is displayed. Window Size: Scale to Fit Window
--depth Color depth for the application. Color Depth
--icon Webtop icon for the application. Icon
--hints String containing additional name-value data for the application. Hints
--clipboardlevel Clipboard security level for the application. Copy and Paste: Application’s Clipboard Security Level
--roottype Appearance of the root window. Window Color
--rootcolor Color of the root window. Window Color: Custom Color
--compression Whether the Adaptive Internet Protocol (AIP) compresses commands for transmission. Command Compression
--execution Whether the Adaptive Internet Protocol (AIP) always executes commands in order, or optimizes commands for performance reasons. Command Execution
--quality The effective color depth displayed on client devices. Color Quality
--interlaced Enables interlaced image transmission. Interlaced Images
--accel Enables graphics acceleration for the application’s display. Graphics Acceleration
--delayed Enables delayed updates of the application’s display. Delayed Updates
--ldapusers Assigns the application to the specified LDAP users. Assigned User Profiles Tab
--ldapgroups Assigns the application to the specified LDAP groups. Assigned User Profiles Tab
--ldapsearch Assigns the application to the users that match the LDAP search criteria. Assigned User Profiles Tab
--loadbal Load balancing algorithm to use. Application Load Balancing
--env Environment variable settings needed to run the application. Environment Variables
--login The login script used to start the application. Login Script
--winmgr The Window Manager to use for the application. Window Manager
--resumetimeout Number of minutes the application is resumable for. Application Resumability: Timeout
--middlemouse Timeout for emulating a middle mouse button click using a two-button mouse. Middle Mouse Timeout
--force3button Specifies that the application only supports a 3-button mouse. Mouse
--windowclose Effect on application session of closing the main application window. Window Close Action
--euro Keycode mapping required by the application to support the euro character. Euro Character
--dpi Monitor resolution that SGD reports to X applications. Monitor Resolution
--keepopen Keep open the connection used to start the application. Keep Launch Connection Open
--lockkeymap Prevents applications from changing keyboard mappings. Keyboard Map: Locked
--share Enables resource sharing for similar application sessions. Share Resources Between Similar Sessions
--securityextension Enables the X Security Extension for the application. X Security Extension
--ssharguments Command-line arguments for the ssh client. Connection Method: ssh Arguments
--unixaudiopreload Enables the SGD audio redirection library. Audio Redirection Library
--remotewindowkeys Sends window management key strokes to the remote session. Window Management Keys
--file Batch file used to create multiple objects within the organizational hierarchy.  

To batch-create multiple objects, use the --file option. Use the other options to create a single object.

Examples

The following example creates a new X application object for the application XFinance. The application can be run on the application servers paris, bonn or lisbon. Application server load balancing decides which one to use.

tarantella object new_xapp \
  --name "o=applications/ou=Finance/cn=XFinance" \
  --width 1000  --height 800 \
  --app /usr/local/bin/xfinance \
  --appserv "o=appservers/ou=Finance/cn=paris" \
            "o=appservers/ou=Finance/cn=bonn" \
            "o=appservers/cn=lisbon"

tarantella object remove_host

Removes application servers from the list of those that can run an application, for application server load balancing.

Syntax

tarantella object remove_host { --name obj...
                                --host hobj...
                              } | --file file

Description

The following table shows the available options for this command.


Option Description
--name Specifies the names of application objects you want to configure load balancing for.
--host Specifies the names of application server objects you want to remove from the load balancing pool.
--file Specifies a file containing a batch of commands to configure application server load balancing.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example removes the application server rome from the load balancing pool for the application Slide-o-Win.

tarantella object remove_host \
  --name "o=applications/cn=Slide-o-Win" \
  --host "o=appservers/ou=Sales/cn=rome"

The following example removes the group WinHosts from the load balancing pool for the applications Write-o-Win and Slide-o-Win. Load balancing is no longer performed across all the application severs in WinHosts.

tarantella object remove_host \
  --name "o=applications/cn=Write-o-Win" \
         "o=applications/cn=Slide-o-Win" \
  --host "o=appservers/cn=WinHosts"

tarantella object remove_link

Removes links from webtops.

Syntax

tarantella object remove_link { --name obj...
                                --link lobj...
                              } | --file file

Description

The following table shows the available options for this command.


Option Description
--name Specifies the names of objects you want to remove webtop links for.
--link Specifies the names of objects you want to remove from the webtop.
--file Specifies a file containing a batch of commands to remove links from webtops.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example removes the Write-o-Win application from Violet Carson’s webtop.

tarantella object remove_link \
  --name "o=Indigo Insurance/ou=Sales/cn=Violet Carson" \
  --link "o=applications/cn=Write-o-Win"

The following example removes the group Applications from the webtops of the organizational units Sales and Marketing. Everyone who inherits webtop content from one of these OUs (for example, they belong to that OU and Inherit Assigned Applications from Parent is selected for their user profile object) no longer sees all the applications in the group on their webtop. However, they might still see an application if it is inherited from elsewhere.

tarantella object remove_link \
  --name "o=Indigo Insurance/ou=Sales" \
         "o=Indigo Insurance/ou=Marketing" \
  --link "o=applications/cn=Applications"

tarantella object remove_member

Removes objects from groups.

Syntax

tarantella object remove_member { --name obj...
                                  --member mobj...
                                } | --file file

Description

The following table shows the available options for this command.


Option Description
--name Specifies the names of group objects you want to remove members from.
--member Specifies the names of objects you want to remove from the groups.
--file Specifies a file containing a batch of commands to remove group members.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example removes the Write-o-Win application from the group Applications.

tarantella object remove_member \
  --name "o=applications/cn=Applications" \
  --member "o=applications/cn=Write-o-Win"

The following example removes the three application server objects rome, brussels and berlin from the group WinHosts.

tarantella object remove_member \
  --name "o=appservers/cn=WinHosts" \
  --member "o=appservers/ou=Sales/cn=rome" \
           "o=appservers/cn=brussels" \
           "o=appservers/ou=Marketing/cn=berlin"

tarantella object rename

Renames or moves an object in the organizational hierarchy.

Syntax

tarantella object rename {   --name obj...
                             --newname newobj...
                           } | --file file

Description

The following table shows the available options for this command.


Option Description
--name Specifies the name of the object you want to rename or move.
--newname Specifies the new name of the object.
--file Specifies a file containing a batch of commands to rename or move objects.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example renames the user profile object for Elizabeth Blue to Liz Blue.

tarantella object rename \
  --name "o=Indigo Insurance/ou=Sales/cn=Elizabeth Blue" \
  --newname "o=Indigo Insurance/ou=Sales/cn=Liz Blue"

The following example moves Ginger Butcher between the organizational units IT and Sales.

tarantella object rename \
  --name "o=Indigo Insurance/ou=IT/cn=Ginger Butcher" \
  --newname "o=Indigo Insurance/ou=Sales/cn=Ginger Butcher"

tarantella object script

Runs a batch script of tarantella object commands, or enables commands to be run interactively.

Syntax

tarantella object script

Description

The batch script consists of standard tarantella object commands, one per line, without the tarantella object prefix. For example, use edit rather than tarantella object edit.

The batch script can use a back slash (\) to break commands across multiple lines. Lines beginning with a hash (#) are treated as comments and ignored.

If you need to include quotes (") or a backslash (\) character in any of the values for the commands, you must backslash protect them. For example, to use "c:\ Program Files" as a value for the --args option, type the following: --args "\"c:\\Program Files\""

The command reads from standard input. For example, you can use a “here-document” to run a batch script:

$ tarantella object script <<EOF
commands
EOF

If standard input is empty, you can run tarantella object commands interactively.

Examples

The following example adds the group Applications to the organizational units Sales and Marketing, and sets the Sales OU’s Inherit Assigned Applications from Parent attribute to false.

tarantella object script <<EOF
add_link \
  --name "o=Indigo Insurance/ou=Sales" \
         "o=Indigo Insurance/ou=Marketing" \
  --link "o=Indigo Insurance/cn=Applications"
edit \
  --name "o=Indigo Insurance/ou=Sales" \
  --inherit false
EOF


The tarantella passcache command

This command manipulates the application server password cache. SGD Administrators can create, modify, delete and examine entries.

Syntax

tarantella passcache new | edit | list | delete

Description

The following table shows the available subcommands for this command.


Subcommand Description More Information
new Creates entries in the password cache. tarantella passcache new
edit Modifies existing entries in the password cache. tarantella passcache edit
list Lists the contents of the password cache. tarantella passcache list
delete Deletes entries from the password cache. tarantella passcache delete



Note - All commands include a --help option. You can use tarantella passcache command --help to get help on a specific command.



Examples

The following example creates a password cache entry for the SGD user Indigo Jones, on the application server represented by the application server object prague.

tarantella passcache new \
  --person "o=Indigo Insurance/cn=Indigo Jones" \
  --resource "o=Indigo Insurance/cn=prague" \
  --resuser indigo \
  --respass rainbow

The following example lists entries in the password cache for the SGD user Indigo Jones.

tarantella passcache list \
  --person "o=Indigo Insurance/cn=Indigo Jones"

tarantella passcache delete

Deletes entries in the application server password cache.



Note - You can also use this command to delete the decision to always use a smart card to authenticate to an application server.



Syntax

tarantella passcache delete { [ --person pobj | --anon | --ldap ]
                              [ --resource resource ]
                            } | --file file

Description

The following table shows the available options for this command.


Option Description
--person Specifies the name of the user profile object to delete the password cache entry for.
--anon Removes the password cache entry for all anonymous users.
--ldap Deletes the password cache entry for LDAP integration. This special entry is only used with LDAP authentication. This is the user name and password for the LDAP directory server that you enter on the Global Settings ⇒ SGD Authentication tab of the Administration Console.

Use a full user name such as cn=Bill Orange,cn=Users,dc=indigo-insurance,dc=com.

If you specify --ldap, the --resource option is ignored.

--resource Specifies the application server or Microsoft Windows domain the password cache entry applies to. For the resource, use the name. This can be one of the following:
  • An application server object, for example "o=appservers/cn=paris".

  • A DNS name, for example ".../_dns/paris.indigo-insurance.com".

  • A Windows domain, for example ".../_wns/indigo.dom".

  • ".../_array" to mean the array. This is used when caching the password used to log in to SGD (see Password Cache Usage).

--file Specifies a file containing password cache entries to delete.

If neither --person, --anon nor --ldap is specified, all password cache entries for the specified resource are deleted.

If --resource is not specified, all the password cache entries for the person (or anonymous user) are deleted.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example deletes all password cache entries for the user Indigo Jones.

tarantella passcache delete \
  --person "o=Indigo Insurance/cn=Indigo Jones"

The following example deletes all password cache entries for anonymous users on the application server prague.indigo-insurance.com.

tarantella passcache delete \
  --anon \
  --resource .../_dns/prague.indigo-insurance.com

tarantella passcache edit

Edits entries in the application server password cache.

Syntax

tarantella passcache edit { 
{ --person pobj | --anon | --ldap }
  --resource resource 
  --resuser resuser 
[ --respass respass ]
} | --file file

Description

The following table shows the available options for this command.


Option Description
--person Specifies the name of the user profile object to edit the password cache entry for.
--anon Edits a password cache entry for anonymous users.
--ldap Edits the password cache entry for LDAP integration. This special entry is only used with LDAP authentication. This is the user name and password for the LDAP directory server that you enter on the Global Settings ⇒ SGD Authentication tab of the Administration Console.

Use a full user name such as cn=Bill Orange,cn=Users,dc=indigo-insurance,dc=com.

If you specify --ldap, the --resource option is ignored.

--resource Specifies the application server or Microsoft Windows domain the password cache entry applies to. For the resource, use the name. This can be one of the following:
  • A application server object, for example "o=appservers/cn=paris".

  • A DNS name, for example ".../_dns/paris.indigo-insurance.com".

  • A Windows domain, for example ".../_wns/indigo.dom".

  • ".../_array" to mean the array. This is used when caching the password used to log in to SGD (see Password Cache Usage).

--resuser Identifies the user name appropriate to the resource. Set this to the text the user types in the authentication box for this resource.
--respass Specifies the password associated with --resuser.

If you omit this option, you are prompted for the password.

--file Specifies a file containing password cache entries to edit.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example edits the password cache entry for the SGD user Indigo Jones, on the application server represented by the application server object prague.

tarantella passcache edit \
  --person "o=Indigo Insurance/cn=Indigo Jones" \
  --resource "o=appservers/cn=prague" \
  --resuser indigo \
  --respass rainbow

The following example edits the password cache entry for anonymous users on the application server paris.indigo-insurance.com.

tarantella passcache edit \
  --anon \
  --resource .../_dns/paris.indigo-insurance.com

tarantella passcache list

Lists entries in the application server password cache.

Syntax

tarantella passcache list { [ --person pobj | --anon | --ldap ]
                            [ --resource resource ]
                            [ --resuser resuser ]
                            [ --format text | xml ]
                          } | --file file

Description

The following table shows the available options for this command.


Option Description
--person Specifies the name of the user profile object to list the password cache entry for.
--anon Lists password cache entries for anonymous users.
--ldap Lists the password cache entry for LDAP integration. This special entry is only used with LDAP authentication. This is the user name and password for the LDAP directory server that you enter on the Global Settings ⇒ SGD Authentication tab of the Administration Console.

Use a full user name such as cn=Bill Orange,cn=Users,dc=indigo-insurance,dc=com.

If you specify --ldap, the --resource option is ignored.

--resource Lists password cache entries for an application server or Microsoft Windows domain. For the resource, use the name. This can be one of the following:
  • A application server object, for example "o=appservers/cn=paris".

  • A DNS name, for example ".../_dns/paris.indigo-insurance.com".

  • A Windows domain, for example ".../_wns/indigo.dom".

  • ".../_array" to mean the array. This is used when caching the password used to log in to SGD (see Password Cache Usage).

--resuser Lists password cache entries for a particular application server user name.
--format Specifies the output format (default setting is text).
--file Specifies a file containing password cache entries to list.

If you omit all arguments, or just specify --format, all entries in the password cache are displayed.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example lists entries in the password cache for the SGD user Indigo Jones.

tarantella passcache list \
  --person "o=Indigo Insurance/cn=Indigo Jones"

The following example lists all entries in the password cache.

tarantella passcache list

tarantella passcache new

Syntax

tarantella passcache new { 
{ --person pobj | --anon | --ldap }
--resource resource 
--resuser resuser 
[ --respass respass ]
} | --file file

Description

Adds entries to the application server password cache.

The following table shows available options for this command.


Option Description
--person Specifies the name of the user profile object to create a password cache entry for.
--anon Creates a password cache entry for anonymous users.
--ldap Creates a password cache entry for LDAP integration. This special entry is only used with the LDAP authorisation. This is the user name and password for the LDAP directory server that you enter on the Global Settings ⇒ SGD Authentication tab of the Administration Console.

Use a full user name such as cn=Bill Orange,cn=Users,dc=indigo-insurance,dc=com.

If you specify --ldap, the --resource option is ignored.

--resource Specifies the application server or Microsoft Windows domain the password cache entry applies to. For the resource, use the name. This can be one of the following:
  • A application server object, for example "o=appservers/cn=paris".

  • A DNS name, for example ".../_dns/paris.indigo-insurance.com".

  • A Windows domain, for example ".../_wns/indigo.dom".

  • ".../_array" to mean the array. This is used when caching the password used to log in to SGD (see Password Cache Usage).

--resuser Identifies the user name appropriate to the resource. Set this to the text the user types in the authentication box for this resource.
--respass Specifies the password associated with --resuser.

If you omit this option, you are prompted for the password.

--file Specifies a file containing entries to add to the password cache.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example creates a password cache entry for the SGD user Indigo Jones, on the application server represented by the application server object prague.

tarantella passcache new \
  --person "o=Indigo Insurance/cn=Indigo Jones" \
  --resource "o=appservers/cn=prague" \
  --resuser indigo \
  --respass rainbow

The following example creates a password cache entry for anonymous users on the application server paris.indigo-insurance.com, prompting for the password.

tarantella passcache new \
  --anon \
  --resuser \
  --resource .../_dns/paris.indigo-insurance.com


The tarantella print command

This command enables you to administer SGD printing services across the array.

Syntax

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

Description

The following table shows the available subcommands for this command.


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



Note - All commands include a --help option. You can use tarantella print command--help to get help on a specific command.



Examples

The following example starts SGD printing services for the array.

tarantella print start

The following example lists all print jobs for Bill Orange.

tarantella print list --person "o=Indigo Insurance/ou=IT/cn=Bill Orange"

tarantella print cancel

Cancels SGD print jobs that are currently spooled.

You can run this command on any SGD server in the array.

Syntax

tarantella print cancel { --all
			| --jobid id...
			| --person pobj... [--server serv]
			| --server serv }

Description

The folowing table shows the available options for this command.


Option Description
--all Cancels all print jobs spooled across the array.
--jobid Cancels jobs with the specified job IDs.
--person Cancels jobs belonging to each specified user profile, which must be the name.

If this is used without --server, SGD cancels all print jobs for each specifed user profile.

--server Cancels jobs on each SGD server listed. Use the peer DNS name for each server.

If this is used with --person, SGD only cancels the print jobs for each specified user profile on each specified server.


Examples

The following example cancels print jobs for Bill Orange.

tarantella print cancel --person "o=Indigo Insurance/ou=IT/cn=Bill Orange"

The following example cancels all print jobs on the SGD server detroit.

tarantella print cancel --server "detroit.indigo-insurance.com"

tarantella print list

Lists print jobs currently spooled.

You can run this command on any SGD server in the array.

Syntax

tarantella print list { --jobid id... | [ --person pobj... ] 
[ --server serv... ]
}
[ --format text|brief ]

Description

The following table shows the available options for this command.


Option Description
--jobid Lists jobs with the specified job IDs.
--person Lists jobs belonging to each specified person, which must be the name.
--server Lists jobs for each specified SGD server. Use the peer DNS name for each server.

If this is used with the --person option, SGD only lists the spooled print jobs for the specified user profile on that server.

--format Specifies the output format.

The “text” format displays a block of text for each print job, showing each print job attribute (for example, the job ID and job owner) on a new line. A blank line separates each job. This is the default.

The “brief” format shows print job attributes on one line.


If you omit --jobid, and --person or --server are used, all print jobs across the array are listed.

Examples

The following example lists print jobs for Bill Orange, in “text” format.

tarantella print list --person "o=Indigo Insurance/ou=IT/cn=Bill Orange"

The following example lists print jobs in “text” format for Bill Orange and Rusty Spanner on the SGD servers detroit and chicago.

tarantella print list \
--person "o=Indigo Insurance/ou=IT/cn=Bill Orange" \
"o=Indigo Insurance/ou=IT/cn=Rusty Spanner" \
--server "detroit.indigo-insurance.com" \
"chicago.indigo-insurance.com"

tarantella print move

Moves queued print jobs from one SGD server to another.

If an SGD server is temporarily unavailable, you can use this command to move the print jobs that are “stranded” on that server.



Note - This command only moves the print jobs that are currently in the SGD print queue (/install-dir/var/print/queue).



Syntax

tarantella print move --server serv
		[ --printer printer_name ]
		[ --cups {y | n |auto} ]
		[ --preserve ]

Description

The following table shows the available options for this command.


Option Description
--cups Indicates that the SGD server you are moving print jobs from uses the Common UNIX Printing System (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).

--preserve Forces SGD to copy rather than move the print jobs to the target SGD server. The original print jobs are kept in the SGD print queue.

Note - If SGD printing services are restarted on the original SGD server and the print jobs have not been deleted, they are printed.

--printer The name of the printer on the SGD server where you are moving the print jobs. If you leave out this argument, a default of tta_printer is used.
--server The fully qualified peer DNS name of the SGD server where you are moving the print jobs.

Examples

The following example moves print jobs from the SGD server where the command is run to the printer called tta_boston on the SGD server boston.indigo-insurance.com.

tarantella print move --server boston.indigo-insurance.com --printer tta_boston

tarantella print pause

You can run this command on any SGD server in the array.

Pauses SGD printing services. New print jobs continue to spool, but do not print until printing is resumed using tarantella print resume.

If --server is not used, this command pauses printing services across the array.



Note - Pausing printing services on individual SGD servers in the array can cause problems for users. Whenever you pause printing services, do so for the whole array.



Syntax

tarantella print pause [ --server serv... ]

Description

The following table shows the available options for this command.


Option Description
--server Pauses printing services on each SGD server listed. Use the peer DNS name for each server.

Examples

The following example pauses printing services across the array.

tarantella print pause

The following example pauses printing services on the SGD servers detroit and chicago.

tarantella print pause --server "detroit.indigo-insurance.com" "chicago.indigo-insurance.com"

tarantella print resume

Resumes SGD printing services, previously suspended with tarantella print pause. Any spooled jobs begin to print.

If --server is not used, this command resumes printing services across the array.

You can run this command on any SGD server in the array.



Note - Resuming printing services on individual SGD servers in the array can cause problems for users. Whenever you resume printing services, do so for the whole array.



Syntax

tarantella print resume [ --server serv... ]

Description

The following table shows the available options for this command.


Option Description
--server Resumes printing services on each SGD server listed. Use the peer DNS name for each server.

Examples

The following example resumes printing services across the array.

tarantella print resume

The following example resumes printing services on the SGD servers detroit and chicago.

tarantella print resume --server "detroit.indigo-insurance.com" "chicago.indigo-insurance.com"

tarantella print start

Starts SGD printing services. If --server is not used, this command starts printing services across the array.

You can run this command on any SGD server in the array.



Note - Starting printing services on individual SGD servers in the array can cause problems for users. Whenever you start printing services, do so for the whole array.



Syntax

tarantella print start [ --server serv... ]

Description

The following table shows the available options for this command.


Option Description
--server Starts printing services on each SGD server listed. Use the peer DNS name for each server.

Examples

The following example starts printing services across the array.

tarantella print start

The following example starts printing services on the SGD server detroit.

tarantella print start --server "detroit.indigo-insurance.com"

tarantella print status

Displays information about SGD printing services, including the following:

You can run this command on any SGD server in the array.

Syntax

tarantella print status [ --summary | --server serv | --namemapping ]

Description

The following table shows the available options for this command.


Option Description
--summary Shows information for the array.
--server Shows information for the SGD server listed. Use the peer DNS name for the server.
--namemapping Lists all the current name mappings used for printing. The print name mapping table ensures that users can print from an application and then exit the application, without losing the print job.

These name mappings expire in time. You can set the expiry timeout on the Security tab of the Global Settings tab in the Administration Console.


Examples

The following example displays information about SGD printing services for the array.

tarantella print status --summary

tarantella print stop

Stops SGD printing services. Print jobs are not accepted and do not spool.

If --server is not used, this command stops printing services across the array.

You can run this command on any SGD server in the array.



Note - Stopping printing services on individual SGD servers in the array can cause problems for users. Whenever you stop printing services, do so for the whole array.



Syntax

tarantella print stop  [ --server serv... ][ --purge ]

Description

The following table shows the available options for this command.


Option Description
--purge Removes all pending print jobs. If you omit this, print jobs that are currently spooled are printed.
--server Stops printing services on each SGD server listed. Use the peer DNS name for each server

Examples

The following example stops printing services across the array, removing all pending print jobs.

tarantella print stop --purge

The following example stops printing services on the SGD server detroit.

tarantella print stop --server "detroit.indigo-insurance.com"


The tarantella query command

Examines the server’s log files.

Syntax

tarantella query audit | billing | errlog | uptime

Description

The following table shows the available subcommands for this command.


Subcommand Description More Information
audit Displays log entries matching some criteria. tarantella query audit
billing Queries billing log files. tarantella query billing
errlog Displays the error log of SGD components. tarantella query errlog
uptime Displays how long an SGD server has been available for. tarantella query uptime



Note - All commands include a --help option. You can use tarantella query command --help to get help on a specific command.



Examples

The following example displays all error logs.

tarantella query errlog

The following example displays how long the SGD server newyork.indigo-insurance.com has been available.

tarantella query uptime --server newyork.indigo-insurance.com

tarantella query audit

Displays all log entries matching some criteria.

Syntax

tarantella query audit { 
  --app app |	
  --person person | 
  --host host | 
  --filter filter }
[ --server arrayhost ]
[ --format text|csv|xml ]

Description

The following table shows the available options for this command.


Option Description
--app Displays log entries referring to a specific application. Use the object name for the application.
--person Displays log entries referring to a specific person. Use the object name for the person.
--host Displays log entries referring to a specific SGD server. Use the object name or a peer DNS name for the server.
--filter An RFC2254-compliant LDAP search filter to find matching entries to display. Enclose the filter in quotes. You can use the "=", "~=", "<=" and ">=" matching rules in the filter.
--server Only show log entries from the specified SGD server (use a peer DNS name). If you omit this option, log entries across the entire array are displayed.
--format Specifies the output format (the default setting is text). If you select the text format, SGD formats the log output so that it is easy to read on screen but it does not show every detail logged. Using the csv format shows every detail logged but it is only suitable for outputting to a file.



Note - The output that you see depends on the Log Filter settings for the array. To produce log entries for processing by this command, make sure the Log Filter attribute on the Monitoring tab of the General Settings tab in the Administration Console includes at least one filter that outputs to a .jsl file.



Using a Filter

The attributes you use in the filter are the log fields used in the .jsl log files. The following table lists the commonly used attributes.


Field Name Description
log-category The logging component/sub-component/severity setting used in the log filters. For example, to find entries for a server/printing/* log filter, you can use a "(log-category=*printing*)" filter
log-date The system date and time when the event took place. The format is yyyy/MM/dd HH:mm:ss.SSS.
log-ip-address The IP address of a client or server associated with an event.
log-keyword The keyword for auditable events.
log-localhost The peer DNS name of the SGD server where the event took place.
log-pid The process ID of the event.
log-security-type The type of security used on a connection, std or ssl.
log-systime The system time in milliseconds (UTC time) when the event took place.
log-tfn-name The name of an object associated with an event. For example, starting an application session can record the name of the user, the application and the SGD server.



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



Examples

The following example displays all log entries for the UNIX user indigo that were logged on the SGD server boston.indigo-insurance.com.

tarantella query audit \
  --person .../_user/indigo \
  --server boston.indigo-insurance.com

The following example outputs all log entries that refer to the Write-o-Win application, in comma-separated values (CSV) format.

tarantella query audit \
  --app "o=applications/cn=Write-o-win" \
  --format csv

The following example outputs all log errors that occurred on or after 23 October 2003 for the Write-o-Win application, in human-readable text format.

tarantella query audit \
  --filter "(&(log-category=*error*)(log-tfn-name=o=applications/cn=Write-o-win) \
(log-date>=2003/10/23 00:00:00.0))" \
  --format text

tarantella query billing

Outputs billing information for the array, or for a subset of the array, over a time period. Information is displayed on screen in CSV format.

Syntax

tarantella query billing 
	{ --full | --sessions | --summary }
	  --start date 
	  --days days 
	  --end date 
	[ --servers arrayhost... ]

Description

The following table shows the available options for this command.


Option Description
--full Displays detailed information for all user sessions and application sessions.
--sessions Displays information for all application sessions.
--summary Displays a short summary of billing information and an application session summary.
--start Specifies the start of the billing period. The format is YYYY/MM/DD, for example, "2000/05/01".
--days Specifies the number of days from the date specified by --start to display billing information.
--end Specifies the end of the billing period. The format is YYYY/MM/DD, for example, “2000/05/02”. The end date is exclusive. This means, for example, that --start 2001/01/19 --end 2001/01/23 is the same as --start 2001/01/19 --days 4. Both examples query data covering the 19th, 20th, 21st and 22nd.
--servers Only reports billing information from the named SGD servers (use peer DNS names). If you omit --servers, billing information across the array is reported.

The billing files are written at midnight local time each day.

You must run this command on the primary server in the array.



Note - You must enable billing services (see Billing Service) and restart all SGD servers in the array before any data is logged.



Examples

The following example displays billing information for the entire array, for the 30 days from May 1, 2000.

tarantella query billing \
  --full \
  --start "2000/05/01" \
  --days 30

The following example displays a short summary of billing information for the servers prague and paris, for the 30 days from January 1 2000.

tarantella query billing \
  --summary \
  --start "2000/01/01" \
  --days 30 \
  --servers prague.indigo-insurance.com \
            paris.indigo-insurance.com

The following example displays billing information for all application sessions for the entire array for the period January 19 2001 to January 22 2001 and outputs the results to a file called Sessions.csv.

tarantella query billing \
  --sessions \
  --start "2000/01/19" \
  --end "2000/01/23" \
  > sessions.csv

tarantella query errlog

Displays the error logs of SGD components.

Syntax

tarantella query errlog
	[ all|xpe|tpe|print|jserver|pemanager|proxy|wm ]
	[ --server arrayhost ]

Description

The following table shows the available options for this command.


Option Description
all | xpe | tpe | print | jserver | pemanager | proxy | wm Specifies the component error log to display. Use all (the default) to display all error logs.
--server Displays error logs from the named SGD server (use a peer DNS name). If you omit this option, error logs from all SGD servers in the array are displayed.



Note - To display error log information from the JServer component, make sure the Log Filter attribute on the Global Settings ⇒ Monitoring tab of the Administration Console includes at least one filter that outputs to an error.log file. The attribute does include this, by default.



Examples

The following example displays all error logs.

tarantella query errlog

The following example displays the X Protocol Engine error log on the SGD server newyork.indigo-insurance.com.

tarantella query errlog xpe --server newyork.indigo-insurance.com

tarantella query uptime

Displays how long SGD servers have been available for.

Syntax

tarantella query uptime [ --server arrayhost ]

Description

The following table shows the available options for this command.


Option Description
--server Display information for the specified SGD server (use a peer DNS name). If you omit this option, information for all SGD servers in the array is displayed.

Examples

The following example displays how long all SGD servers in the array have been available for.

tarantella query uptime


The tarantella restart command

Stops and then restarts SGD services on the SGD server, prompting if users are currently connected.

Syntax

tarantella restart [ --warm | --force | --kill ] [ --quiet ]

Description

This command does not restart the SGD Web Server or SGD web services. Use the tarantella webserver restart command to restart these services.

The following table shows the available options for this command.


Option Description
--quiet Does not prompt. Stops SGD services even if users are connected.
--warm Tries a “warm restart” of the SGD server. This restarts the JServer component without affecting other components.

This has no effect on user sessions or application sessions.

Only use this option if no users can log in to SGD or launch applications and no specific reason is found.

--force Tries harder to stop SGD services.
--kill Kills the process IDs used by SGD services.

Only use this option if you are having difficulty stopping the SGD server by other means.


Stopping SGD services causes all application sessions (including suspended application sessions) to be terminated.

Examples

The following example stops and then restarts SGD services without displaying a confirmation message if users are currently connected.

tarantella restart --quiet


The tarantella role command

You use this command to give users specific roles, and to give them webtop links that apply to that role.

Syntax

tarantella role add_link | add_member | list | list_links | list_members | remove_link | remove_member

Description

The following table shows the available subcommands for this command.


Subcommand Description More Information
add_link Adds links to the webtops of occupants of particular roles. tarantella role add_link
add_member Adds occupants to particular roles. tarantella role add_member
list Lists and describes all available roles. tarantella role list
list_links Lists the webtop links for occupants of particular roles. tarantella role list_links
list_members Lists the occupants of particular roles. tarantella role list_members
remove_link Removes links from the webtops of users occupying particular roles. tarantella role remove_link
remove_member Removes occupants from particular roles. tarantella role remove_member



Note - All commands include a --help option. You can use tarantella role subcommand --help to get help on a specific command.



Examples

The following example lists all available roles.

tarantella role list

The following example adds a link for the application Indigo Time to the webtops of users occupying the Global Administrators role.

tarantella role add_link \
  --role global \
  --link "o=applications/cn=Indigo Time"

tarantella role add_link

Adds links to the webtops of users occupying particular roles.

Syntax

tarantella role add_link { 
			--role rolename
			--link lobj...
                         } | --file file

Description

The following table shows the available options for this command.


Option Description
--role Specifies the name of a role, for example global. Use tarantella role list to find out the available roles.
--link Specifies the names of objects to add to the webtops of users occupying the role, for example, o=applications/cn=Indigo Time.
--file Specifies a file containing a batch of commands to add links to webtops of users with a particular role.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example adds a link for the application Indigo Time to the webtops of users occupying the Global Administrators role.

tarantella role add_link \
  --role global \
  --link "o=applications/cn=Indigo Time"

tarantella role add_member

Adds occupants to particular roles.

Syntax

tarantella role add_member { 
		--role rolename 
		--member mobj...
	} | --file file

Description

The following table shows the available options for this command.


Option Description
--role Specifies the name of a role, for example global. Use tarantella role list to find out the available roles.
--member Specifies the names of user profile objects or profile objects for the users you want to occupy the role.
--file Specifies a file containing a batch of commands to add occupants to particular roles.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example adds Sid Cerise to the Global Administrators role.

tarantella role add_member \
  --role global \
  --member "o=Indigo Insurance/ou=Finance/cn=Sid Cerise"

tarantella role list

Lists and describes all available roles, including the name of the role object applicable to each role.

Syntax

tarantella role list

Description

Use the short name (for example, “global”) with other tarantella role commands.

Examples

The following example lists all available roles.

tarantella role list

tarantella role list_links

Lists the webtop links for occupants of particular roles. The name for each link is shown.

Syntax

tarantella role list_links --role rolename | --file file

Description

The following table shows the available options for this command.


Option Description
--role Specifies the name of a role, for example global. Use tarantella role list to find out the available roles.
--file Specifies a file containing a batch of commands to list the webtop links for role occupants.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example lists the names of all webtop links for occupants of the Global Administrators role.

tarantella role list_links --role global

tarantella role list_members

Lists the occupants of particular roles. The name for each member is shown.

Syntax

tarantella role list_members --role rolename | --file file

Description

The following table shows the available options for this command.


Option Description
--role Specifies the name of a role, for example global. Use tarantella role list to find out the available roles.
--file Specifies a file containing a batch of commands to list the occupants of a particular role.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example lists the names of all occupants of the Global Administrators role.

tarantella role list_members --role global

tarantella role remove_link

Removes links from the webtops of users occupying particular roles.

Syntax

tarantella role remove_link {
		--role rolename
		--link lobj...
	} | --file file

Description

The following table shows the available options for this command.


Option Description
--role Specifies the name of a role, for example global. Use tarantella role list to find out the available roles.
--link Specifies the names of objects to remove from the webtops of users occupying the role. For example, o=applications/cn=Indigo Time.
--file Specifies a file containing a batch of commands to remove links from the webtops of users with a particular role.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example removes a link for the Write-o-Win application from the webtops of members of the Global Administrators role.

tarantella role remove_link \
  --role global \
  --link "o=applications/cn=Write-o-Win"

tarantella role remove_member

Removes occupants from particular roles.

Syntax

tarantella role remove_member {
		--role rolename 
		--member mobj...
	} | --file file

Description

The following table shows the available options for this command.


Option Description
--role Specifies the name of a role, for example global. Use tarantella role list to find out the available roles.
--member Specifies the names of objects for the users you do not want to occupy the role.
--file Specifies a file containing a batch of commands to remove occupants from a particular role.



Note - Make sure you quote any object names containing spaces, for example "o=Indigo Insurance".



Examples

The following example removes Sid Cerise from the Global Administrators role.

tarantella role remove_member \
  --role global \
  --member "o=Indigo Insurance/ou=Finance/cn=Sid Cerise"


The tarantella security command

Controls SGD security services and manages X.509 certificates.

Syntax

tarantella security certinfo | certrequest | certuse | customca | decryptkey | fingerprint | peerca | start | stop

Description

The following table shows the available subcommands for this command.


Subcommand Description More Information
certinfo Displays information about an X.509 certificate or Certificate Signing Request (CSR), and optionally checks whether a specified private key matches the public key contained in a particular certificate. tarantella security certinfo
certrequest Creates a CSR (and a corresponding key pair) which you use to obtain an X.509 certificate for use with SGD security services. tarantella security certrequest
certuse Installs an X.509 certificate (or specifies the location of an installed certificate) for use with SGD security services. tarantella security certuse
customca Installs a root certificate for a custom Certificate Authority (CA) for use with SGD security services. tarantella security customca
decryptkey Decrypts an encrypted private key so that you can use it with SGD. tarantella security decryptkey
fingerprint Displays the fingerprint of the X.509 certificate installed on this SGD server. tarantella security fingerprint
peerca Shows, imports or exports the primary server’s CA certificate used for secure intra-array communication. tarantella security peerca
start Enables secure (SSL) connections. Users who require secure connections are given them. tarantella security start
stop Disables secure (SSL) connections. Users configured for secure connections are given standard connections instead. tarantella security stop



Note - All commands include a --help option. You can use tarantella security subcommand --help to get help on a specific command.



Examples

The following example displays information about the CSR in /tmp/boston.csr.

tarantella security certinfo \
  --csrfile /tmp/boston.csr

The following example decrypts the key /opt/keys/key1, which is stored in Definite Encoding Rules (DER) format, placing the decrypted key in /opt/keys/key2.

tarantella security decryptkey \
  --enckey /opt/keys/key1 \
  --deckey /opt/keys/key2 \
  --format DER

tarantella security certinfo

Displays information about an installed X.509 certificate (--certfile) or a Certificate Signing Request (--csrfile).

Syntax

tarantella security certinfo  [ --certfile certfile [ --keyfile keyfile ] ]
                              [ --checkkey ] [ --full ]
tarantella security certinfo --csrfile csrfile [ --full ]

Description

This command can also check whether a specified private key matches the public key (that is, the public key can decrypt text encrypted with the private key) in a particular certificate.

Use the first form of this command without specifying a certfile and keyfile to check keys and certificates you have already installed using the tarantella security certuse command.

The following table shows the available options for this command.


Option Description
--certfile Specifies the location of a file containing an X.509 certificate. The command displays information about this certificate, including the following:
  • Information about the server and your organization.

  • Alternative DNS names for the server.

  • Credentials of the CA that validated the certificate.

  • Dates for which the certificate is valid.

You must specify the full path to the certificate file.

--keyfile Specifies the location of a private key.

You must specify the full path to the key file.

--checkkey Checks whether a particular private key matches the public key contained in the X.509 certificate specified in the certificate file.
  • If you specify both --certfile and --keyfile, the command checks that the specified private key in the key file matches the public key in the certificate file.

  • If you only specify --certfile, the command assumes that the certificate file contains both a certificate and a private key, and checks that that private key matches the public key in the certificate.

  • If you omit both --certfile and --keyfile, the command checks the certificate and private key installed in the /install-dir/var/tsp directory.

--csrfile Specifies the location of a file containing a CSR. The command displays information about this CSR, including the following:
  • The DNS name (or chosen common name) of the server the CSR is for.

  • Alternative DNS names for the server.

  • Your organization’s name and location.

You must specify the full path to the CSR file.

--full Displays more detailed information about the specified certificate or CSR, for example, the contents of the public keys they contain.

Examples

The following example displays detailed information about the certificate in /opt/certs/newyork.cert.

tarantella security certinfo \
  --certfile /opt/certs/newyork.cert \
  --full

The following example displays information about the certificate in /opt/certs/boston.cert, and checks that the private key /opt/keys/boston.key matches the public key contained in that certificate.

tarantella security certinfo \
  --certfile /opt/certs/boston.cert \
  --keyfile /opt/keys/boston.key \
  --checkkey

The following example displays information about the CSR in /tmp/boston.csr.

tarantella security certinfo \
  --csrfile /tmp/boston.csr

tarantella security certrequest

Generates a CSR, and a public and private key pair.

Syntax

tarantella security certrequest --country country
				  --state state
				  --orgname org
				[ --ouname ou ] 
				[ --email email ] 
				[ --locality locality ] 
				[ --keylength length ]

Description

You send the generated CSR to a supported CA to obtain a certificate for use with SGD security services.

Note the following:

  • If your CA lets you change the hostname stored in the certificate, make sure the certificate contains a fully qualified DNS name (for example, boston.indigo-insurance.com, not boston).

  • If the SGD server has multiple DNS names, for example, it is known by different names inside and outside a firewall, you can specify the additional DNS names as subject alternative names for the certificate. This enables you to associate more than one DNS name with the certificate.

  • Make a copy of the private key and CSR generated by this command and keep them in a safe, secure location, for example, on a floppy disk in a safe. Key information is stored in the /install-dir/var/tsp directory. If your private key is lost or damaged, you will be unable to use any certificate you obtain using the CSR.

  • This command generates a new key pair each time you run it. If you generate a CSR with this command and use it to obtain a certificate, running this command again means you cannot use the old certificate.

You can use the tarantella security certinfo command to display information about certificates and CSRs.

If you do not specify --ouname, --email or --locality SGD simply omits that information from the CSR. There are no default values.

The options that can be used for this command are as follows.


Option Description
--country Specifies the country where your organization is located. Use ISO 3166 country codes. For example, use US for the United States or DE for Germany.
--state Specifies the state or province where your organization is located. Do not use abbreviations here. For example, use Massachusetts rather than Mass. or MA.
--orgname Specifies the official, legal name of your organization.
--ouname Specifies the name of a subdivision (organizational unit) within your organization, if required.

If you do not need to specify an OU, you can use this setting to specify a less formal organization name.

--email Specifies your business email address. This address is used for correspondence between you and the CA you send the CSR to.
--locality Specifies the city or principality where your organization is located, if needed.
--keylength Specifies the length of the key pair. The default is 1024. Use 512-bit or 1024-bit keys.



Note - Make sure you quote any value containing spaces, for example,"Indigo Insurance".



Examples

The following example generates a CSR for Indigo Insurance, located in Massachusetts, with contact Bill Orange.

tarantella security certrequest \
  --country US \
  --state MA \
  --orgname "Indigo Insurance" \
  --email "orange@indigo-insurance.com"

tarantella security certuse

Installs an X.509 certificate (or specifies the location of a previously installed certificate) to be used by SGD security services.

Syntax

tarantella security certuse
tarantella security certuse --certfile cfile [ --keyfile kfile ]

Description

Certificates must be Base 64-encoded PEM-format, with a header line including "BEGIN CERTIFICATE", as used by OpenSSL.

If no arguments are specified, this command reads the certificate from standard input and installs it in /install-dir/var/tsp.

After installing an X.509 certificate, you must restart SGD using the tarantella restart command.

The following table shows the available options for this command.


Option Description
--certfile Specifies the location of a file containing the certificate. If no --keyfile argument is specified, SGD assumes that the certificate file contains both the certificate and the corresponding private key.

You can use this option as follows:

  • To tell SGD about a certificate you have already installed for use with another product (such as a web server). In this case, SGD makes symbolic links to (not copies of) the certificate file (and key file, if specified).

  • To install a certificate received from a CA after generating a CSR using tarantella security certrequest. In this case, SGD installs the certificate in /install-dir/var/tsp for use with SGD security services.

You must specify the full path to the certifiate file.

--keyfile Specifies the location of a file containing the private key required to decrypt the certificate specified by --certfile.

Use this option to tell SGD about a private key you have already installed. If you used the tarantella security certrequest command to generate a CSR and obtain a certificate, you do not need to use this option.

You must specify the full path to the key file.


Examples

The following table shows some example scenarios and the corresponding options to use for the tarantella security certuse command.


Scenario Command
You used tarantella security certrequest to generate a CSR, which you sent to a CA. The CA returned a certificate to you, which you saved in a temporary file /tmp/cert. tarantella security certuse < /tmp/cert
You already have a certificate (you did not use tarantella security certrequest). The certificate is installed in /opt/certs/cert and the key needed to decode it is installed in /opt/keys/key. tarantella security certuse --certfile /opt/certs/cert --keyfile /opt/keys/key
You already have a certificate (you did not use tarantella security certrequest). A single file /opt/certs/cert contains both the certificate and the key needed to decode it. tarantella security certuse --certfile /opt/certs/cert

tarantella security customca

Installs or removes a root certificate for a custom CA for use with SGD security services.

Syntax

tarantella security customca
tarantella security customca --rootfile carootfile | --remove

Description

Certificates must be Base 64-encoded PEM-format, with a header line including "BEGIN CERTIFICATE", as used by OpenSSL.

If no arguments are specified, this command reads the root certificate from standard input.

The following table shows the available options for this command.


Option Description
--rootfile Specifies the location of a file containing the CA’s root certificate. Details are copied to /install-dir/var/tsp for use by SGD security services.

You must specify the full path to the root certificate file.

--remove Removes any custom CA’s root certificate currently installed for use with SGD security services.

Examples

The following example installs a CA’s root certificate from the file/tmp/rootcert, which you can then delete.

tarantella security customca \
  --rootfile /tmp/rootcert

tarantella security decryptkey

Decrypts an encrypted private key so that you can use it with SGD. This enables you to use an X.509 certificate that you are already using with another product (a web server, for example) rather than obtaining a separate certificate for use exclusively with SGD.

Syntax

tarantella security decryptkey --enckey enckeyfile
				  --deckey deckeyfile
				[ --format PEM|DER ]

Description

The following table shows the available options for this command.


Option Description
--enckey Specifies the location of the encrypted private key that you want to decrypt. Only keys encrypted by a product that uses SSLeay or OpenSSL certificate libraries can be decrypted.

You must specify the full path to the encrypted private key file.

--deckey Specifies a file where the decrypted key is stored.

Note - For security reasons, it is very important to restrict access to private keys, especially when stored in an unencrypted form. Access to private keys by unauthorized users can result in a serious security breach. Store private keys accordingly.

You must specify the full path to the decrypted key file.

--format Specifies the format the encrypted key is stored in. Defaults to PEM.



Note - You can only decrypt private keys that were originally encrypted by a product that uses SSLeay or OpenSSL certificate libraries.



See the tarantella security certuse command for information about how to share certificates in this way.

Examples

The following example decrypts the key /opt/keys/key1 (which is stored in DER format), placing the decrypted key in /opt/keys/key2.

tarantella security decryptkey \
  --enckey /opt/keys/key1 \
  --deckey /opt/keys/key2 \
  --format DER

tarantella security fingerprint

Displays the fingerprint of the X.509 certificate installed on the SGD server.

Syntax

tarantella security fingerprint

Description

Use this command to obtain the fingerprint and distribute it to users so that can be sure that the SGD server they are connecting to is a trusted server. See the Sun Secure Global Desktop Administration Guide for details.

Examples

The following example displays the fingerprint of the X.509 certificate installed on the SGD server.

tarantella security fingerprint

tarantella security peerca

Shows, imports or exports the primary server’s CA certificate used for secure intra-array communication.

Syntax

tarantella security peerca [ --show | --import hostname | --export ]

Description

The following table shows the available options for this command.


Option Description
--show Displays the primary server’s CA certificate for the array.
--import Import the CA certificate from the specified server.
--export Export the CA certificate from this server.

Examples

The following example shows the primary server’s CA certificate for the array.

tarantella security peerca --show

tarantella security start

Enables secure (SSL-based) connections for all or part of an array. SGD gives secure connections to those users configured to require them.

Syntax

tarantella security start [ --array | --server serv... ]

Description

To enable secure connections to a particular SGD server you must already have installed an X.509 certificate for that server.

The following table shows the available options for this command.


Option Description
--array Enables secure connections on all servers in the array that have a suitable X.509 certificate.

Note - Only use this option if you have already installed an X.509 certificate on every server in the array.

--server Enables secure connections for the specified servers. Each server name is the peer DNS name of an SGD server in the array.

If you omit both options, secure connections are enabled for the SGD server where the command is run.

Examples

The following example enables secure connections across the array.

tarantella security start --array

tarantella security stop

Disables secure (SSL-based) connections for all or part of an array. Users configured to require secure connections are given standard connections instead, if available.

Syntax

tarantella security stop [ --array | --server serv... ][ --keep ]

Description

The following table shows the available options for this command.


Option Description
--array Disables secure connections on all servers in the array.
--server Disables secure connections for the specified servers. Each server name is the peer DNS name of an SGD server in the array.
--keep Specifies that any existing secure connections are preserved. If omitted, all secure connections are closed.

If you omit both arguments, secure connections are disabled for the SGD server where the command is run.

Examples

The following example disables security across the array, but preserves any existing secure connections.

tarantella security stop --array --keep


The tarantella setup command

Enables you to change Setup options. Follow the instructions on your screen.

Syntax

tarantella setup

Description

You can turn weekly archiving on or off. If archiving is on, you can schedule the time when the log is created.

You can also choose to recreate the default objects and webtop links originally created at installation time. This does not remove any objects you have created, but it does replace any objects with the same names as the originals.

Examples

The following example enables you to change Setup options.

tarantella setup


The tarantella start command

Starts SGD services on the SGD server.

Syntax

tarantella start

Description

Starts SGD services on the SGD server, including SGD printing services.

This command does not start the SGD Web Server or SGD web services. Use the tarantella webserver start command to start these services.

Examples

The following example starts SGD services.

tarantella start


The tarantella start cdm command

Starts CDM services.

Syntax

tarantella start cdm

Description

Starts client drive mapping services on the SGD server where the command is run.

Examples

The following example starts client drive mapping services on the SGD server.

tarantella start cdm


The tarantella status command

Reports SGD server information.

Syntax

tarantella status [ --summary | --byserver | --server serv | --ping [serv] ]
	 [ --format text|xml ] [ --verbose ]

Description

Reports SGD server information, including array details, the number of user sessions and application sessions running or suspended across the array, and how those sessions are distributed.

The following table shows the available options for this command.


Option Description
--summary Summarizes the global information for the array. This is the default setting.
--byserver Displays detailed information for each server in the array.
--server Displays detailed information for the specified server (type in a peer DNS name).
--format Specifies the output format. The default setting is text.
--ping Performs a quick health check of all SGD servers in the array or a single specified SGD server.
--verbose Displays the server health check and lists servers being contacted, before generating the command output.

Examples

The following example summarizes information about sessions across the array.

tarantella status

The following example reports detailed status information for the SGD server boston.indigo-insurance.com.

tarantella status --server boston.indigo-insurance.com


The tarantella stop command

Stops SGD services on the SGD server.

Syntax

tarantella stop [ --force | --kill ] [ --quiet ] 

Description

Stops SGD services on the SGD server, prompting if users are currently connected. This includes SGD printing services.

This command does not stop the SGD Web Server or SGD web services. Use the tarantella webserver stop command to stop these services.

The following table shows the available options for this command.


Option Description
--quiet Does not prompt. Stops SGD services even if users are connected.
--force Tries harder to stop SGD services.
--kill Kills the process IDs used by SGD services.Only use this option if you are having difficulty stopping the SGD server by other means.



Note - Never use the UNIX kill command to stop SGD services.



Stopping SGD services causes all application sessions (including suspended application sessions) to be terminated.

Examples

The following example stops SGD services without displaying a confirmation message if users are currently connected.

tarantella stop --quiet


The tarantella stop cdm command

Stops client drive mapping (CDM) services.

Syntax

tarantella stop cdm

Description

Stops client drive mapping services on the SGD server where the command is run.

Examples

The following example stops client drive mapping services on the SGD server.

tarantella stop cdm


The tarantella tokencache command

This command manipulates the token cache used for logging in with an authentication token. SGD Administrators can list and delete entries in the token cache.

Syntax

tarantella tokencache delete | list

Description

The following table shows the available subcommands for this command.


Subcommand Description More Information
delete Deletes entries from the token cache. tarantella tokencache delete
list Lists the contents of the token cache. tarantella tokencache list



Note - All commands include a --help option. You can use tarantella tokencache command --help to get help on a specific command.



Examples

The following example deletes all entries in the token cache.

tarantella tokencache delete --all

The following example lists all entries in the token cache and the time the tokens were created.

tarantella tokencache list --creationtime 

tarantella tokencache delete

Deletes entries in the token cache. The token cache is used for logging in with an authentication token.

Syntax

tarantella tokencache delete { 
		[ --username username | --all ] 
		[ --format text | xml ] }
		| --file file

Description

The following table shows the available options for this command.


Option Description
--username Specifies the name of the entry to be deleted.
--all Deletes all entries in the cache.
--format Output format (the default setting is text).
--file Specifies a batch file to process. The file contains one line per set of settings, each line using the above options.

Use --file - to read from stdin.


Examples

The following example deletes all entries in the token cache.

tarantella tokencache delete --all

tarantella tokencache list

Lists the contents of the token cache. The token cache is used for logging in with an authentication token.

Syntax

tarantella tokencache list [ --creationtime ] [ --format text | xml ]  

Description

The following table shows the available options for this command.


Option Description
--creationtime Lists the time each token in the cache was created.
--format Specifies the output format (default setting is text).

Examples

The following example lists all entries in the token cache and the time the tokens were created.

tarantella tokencache list --creationtime 


The tarantella tscal command

Use the tarantella tscal command to manage Microsoft Windows Terminal Services Client Access Licenses (CALs) for non-Windows clients.

Syntax

tarantella tscal free | list | return

Description

The following table shows the available subcommands for this command.


Subcommand Description More Information
free Frees a Terminal Services CAL for use by another non-Windows client. tarantella tscal free
list Lists the Terminal Services CALs currently reserved for non-Windows clients. tarantella tscal list
return Returns Terminal Services CALs to the Windows license server. tarantella tscal return



Note - All commands include the --help option. You can use tarantella tscal subcommand --help to get help on a specific command.



Examples

The following example lists the Terminal Services CALs currently reserved for non-Windows clients.

tarantella tscal list

tarantella tscal free

Use the tarantella tscal free command to free a Microsoft Windows Terminal Services CAL so that it can be used by another non-Windows client.

Syntax

tarantella tscal free [ --inuseby user | --calid id ]

Description

You can only free a CAL if the user has no application sessions that use Windows Terminal Services.



Note - Freed CALs are not returned to the Windows license server.



Normally, you do not need to run this command, as SGD automatically frees a CAL as soon as a user exits their last Windows application. However, if an SGD server is removed from an array or it loses contact with the array, it might still be listed as using CALs. In this situation, you can run this command to free a CAL.

If you do not use any arguments, the command frees all CALs that have no application sessions that use Windows Terminal Services.

If you run this command on a secondary server in a SGD array and the primary server is unavailable, the CAL information might not be completely accurate. This is because the primary server is responsible for updating all SGD servers in the array with changes to CAL information. The command warns you if the primary is unavailable.

The following table shows the available options for this command.


Option Description
--inuseby Free only the CALs for a particular user where the user is either of the following:
  • The name of a user.

  • A wild card filter.

The * character is the only character you can use in a wild card filter. It represents a string of any length containing any characters. So, an --inuseby "*green*" argument frees only the unused CALs for users whose name contains the string “green”.

--calid The ID of the CAL you want to free. Use the tarantella tscal list command to obtain the ID of the CAL you wish to free.

Examples

The following example frees the CALs for Elizabeth Blue.

tarantella tscal free --inuseby "o=Indigo Insurance/ou=Sales/cn=Elizabeth Blue"

tarantella tscal list

Use the tarantella tscal list command to list the Microsoft Windows Terminal Services CALs currently reserved for use by non-Windows clients.

Syntax

tarantella tscal list [ --inuseby user | --inuse | --free ] 
                      [ --type name ]
                      [ --format text|xml ]

Description

If you do not use any arguments, the command lists all CALs and shows whether or not they are in use.

If you run this command on a secondary server in an SGD array and the primary server is unavailable, the list might not be completely accurate. This is because the primary server is responsible for updating all SGD servers in the array with changes to CAL information. The command warns you if the primary is unavailable.

The following table shows the available options for this command.


Option Description
--inuseby List only the CALs being used by a particular user where the user is either of the following:
  • The name of a user.

  • A wild card filter.

You can use the tarantella emulatorsession list command to determine the name of a user.

The * character is the only character you can use in a wild card filter. It represents a string of any length containing any characters. So, an --inuseby "*green*" argument lists only the CALs for users whose name contains the string “green”.

--inuse List only the CALs that are currently in use.
--free List only the CALs that are currently not in use.
--type List only the CALs that can connect to a particular type of Terminal Services server. This is either WinNT4-TS-CAL or Win200x-TS-CAL.

Note - The name is not case sensitive.

--format Specifies the output format (default setting is text).

Examples

The following example lists the CALs for non-Windows clients that are currently not in use.

tarantella tscal list --free

tarantella tscal return

Use the tarantella tscal return command to return all free Microsoft Windows Terminal Services CALs to the Windows license server.

Syntax

tarantella tscal return --free

Description



Note - The Windows license server might not reissue the returned CALs until approximately 90 days have elapsed since they were last in use.



Use the tarantella tscal free command to free a CAL so that it can be returned.

Normally, you do not need to run this command, as SGD automatically returns a CAL if it has not been used for 90 days. However, if an SGD server is removed from an array, you can use this command to manually return the CALs.

The following table shows the available options for this command.


Option Description
--free Returns all free CALs to the Windows license server.

Examples

The following example returns all free CALs to the Windows license server.

tarantella tscal return --free


The tarantella uninstall command

Uninstalls SGD or the specified SGD packages.

Syntax

tarantella uninstall { [ package... ] [ --purge ] | --list  }

Description

Removes SGD or parts of it from your system, or lists the installed SGD packages.

The following table shows the available options for this command.


Option Description
package... Specifies individual packages to uninstall. If no packages are specified, the command uninstalls all SGD packages. SGD currently installs as a single package.
--purge If all SGD packages are removed, this option also removes all configuration information related to your organization. If --purge is omitted, configuration information is left intact.
--list Lists all SGD packages currently installed.

Examples

The following example completely uninstalls SGD, removing all configuration information.

tarantella uninstall --purge


The tarantella version command

Reports the version numbers of installed SGD components.

Syntax

tarantella version

Description

Displays the version numbers of SGD components installed on the SGD server, together with information about the SGD server.

Information about installed SGD components is also available on the webtop. Click the ? button, in the lower-left corner of the webtop.

Examples

The following example displays the version numbers of installed SGD components.

tarantella version


The tarantella webserver command

Use the tarantella webserver command to control the SGD Web Server.

Syntax

tarantella webserver start | stop | restart | add_trusted_user | delete_trusted_user | list_trusted_users

Description

This command has no effect on the SGD server.

The following table shows the available subcommands for this command.


Subcommand Description More Information
start Starts the SGD Web Server. tarantella webserver start
stop Stops the SGD Web Server. tarantella webserver stop
restart Restarts the SGD Web Server. tarantella webserver restart
add_trusted_user Adds the user name and password of a user that is to be trusted by the third-party authentication mechanism. tarantella webserver add_trusted_user
delete_trusted_user Deletes the user name and password of a user that is to be trusted by the third-party authentication mechanism. tarantella webserver delete_trusted_user
list_trusted_users Lists the user names of the users that are to be trusted by the third-party authentication mechanism. tarantella webserver list_trusted_users



Note - All commands include the --help option. You can use tarantella webserver subcommand --help to get help on a specific command.



Examples

The following example starts the SGD Web Server.

tarantella webserver start

tarantella webserver add_trusted_user

Adds the user name and password of a user that is to be trusted for third-party authentication.

Syntax

tarantella webserver add_trusted_user username

Description

After you enter the username, SGD prompts you to enter the password. The password must be at least six characters long.

You must restart the SGD Web Server (using tarantella webserver restart) to activate the new user.

You cannot use this command to change the password of a trusted user. You must delete the trusted user first, using tarantella webserver delete_trusted_user.

This command adds the user name to the “database” of Tomcat users in /install‐dir/webserver/tomcat/version/conf/tomcat-users.xml and creates an SHA digest of the password. The user is also assigned the “SGDExternalAuth” role. This role is required to access the SGD external authentication web service.

Examples

The following example adds L3nNy_G0db3r as a trusted user.

tarantella webserver add_trusted_user L3nNy_G0db3r

tarantella webserver delete_trusted_user

Deletes the user name and password of a user that is to be trusted for third-party authentication.

Syntax

tarantella webserver delete_trusted_user username

Description

You must restart the SGD Web Server, using tarantella webserver restart, to deactivate the user.

This command removes the user name from the “database” of Tomcat users in /install-dir/webserver/tomcat/version/conf/tomcat-users.xml.

Examples

The following example deletes L3nNy_G0db3r as a trusted user.

tarantella webserver delete_trusted_user L3nNy_G0db3r

tarantella webserver list_trusted_users

Lists the user names of the users that are to be trusted for third-party authentication.

Syntax

tarantella webserver list_trusted_users

Description

Each user name is separated by a comma. The command also shows whether or not the third-party authentication is currently enabled.

This command lists the user names in the “database” of Tomcat users in /install‐dir/webserver/tomcat/version/conf/tomcat-users.xml.

Examples

The following example lists trusted users.

tarantella webserver list_trusted_users

tarantella webserver start

Use the tarantella webserver start command to start the SGD Web Server and Java Servlet/JavaServer Pages services on the SGD server.

Syntax

tarantella webserver start [ --http ] [ --ssl ] [ --servlet ]

Description

If you do not use any arguments, the command starts both the SGD Web Server and Java Servlet/JavaServer Pages services.

The following table shows the available options for this command.


Option Description
--http Starts the SGD Web Server without starting Java Servlet/JavaServer Pages services.
--servlet Starts Java Servlet/JavaServer Pages services without starting the SGD Web Server.
--ssl Starts the SGD Web Server with SSL enabled.



Note - If you start both the SGD Web Server and Java Servlet/JavaServer Pages services using separate subsequent commands, you must start the Java Servlet/JavaServer Pages services first.



Examples

The following example starts the SGD Web Server and SGD web services.

tarantella webserver start

tarantella webserver stop

Use the tarantella webserver stop command to stop the SGD Web Server and Java Servlet/JavaServer Pages services on the SGD server

Syntax

tarantella webserver stop [ --http ] [ --servlet ]

Description

If you do not use any arguments, the command stops both the SGD Web Server and Java Servlet/JavaServer Pages services.

The following table shows the available options for this command.


Option Description
--http Stops the SGD Web Server without stopping Java Servlet/JavaServer Pages services.
--servlet Stops Java Servlet/JavaServer Pages services without stopping the SGD Web Server.

Examples

The following example stops the SGD Web Server and SGD web services.

tarantella webserver stop

tarantella webserver restart

Use the tarantella webserver restart command to restart the SGD Web Server.

Syntax

tarantella webserver restart [ --http ] [ --ssl ] [ --servlet ]

Description

If you do not use any arguments, the command restarts both the SGD Web Server and Java Servlet/JavaServer Pages services.


Option Description
--http Retarts the SGD Web Server without starting Java Servlet/JavaServer Pages services.
--servlet Restarts Java Servlet/JavaServer Pages services without starting the SGD Web Server.
--ssl Retarts the SGD Web Server with SSL enabled.



Note - If you restart both the SGD Web Server and Java Servlet/JavaServer Pages services using separate subsequent commands, you must restart the Java Servlet/JavaServer Pages services first.



Examples

The following example restarts the SGD Web Server and Java Servlet/JavaServer Pages services.

tarantella webserver restart


The tarantella webtopsession command

This command enables SGD Administrators to list and end user sessions.

Syntax

tarantella webtopsession list | logout

Description

The following table shows the available subcommands for this command.


Subcommand Description More Information
list Lists user sessions matching the person or server specified. tarantella webtopsession list
logout Logs users out of their webtop. tarantella webtopsession logout



Note - All commands include a --help option. You can use tarantella webtopsession subcommand --help to get help on a specific command.



Examples

The following example displays details of all user sessions maintained by the SGD server detroit.

tarantella webtopsession list \
   --server "o=Indigo Insurance/cn=detroit"

The following example logs out Emma Rald from her webtop.

tarantella webtopsession logout \
  --person "o=Indigo Insurance/ou=Marketing/cn=Emma Rald"

tarantella webtopsession list

Lists user sessions matching the person or server specified.

Syntax

tarantella webtopsession list [ --person pobj | --server serv ]
                              [ --format text|count|xml ]

Description

For each session, the following details are displayed:

  • Print state. Shows whether the user has paused printing or not.

  • Client. The IP address of the client.

  • Logged in at. The timestamp when the user logged in.

  • User. The name of the user.

  • Logged in to. The SGD server hosting the user session.

  • Connection type. Whether the connection is a standard or a secure connection.

You can list user session details using the following Administration Console tabs:

  • Sessions tab

  • Secure Global Desktop Servers ⇒ User Sessions tab

  • User Sessions tab for a user profile object

The following table shows the available options for this command.


Option Description
--person Displays details of user sessions matching the person specified. Use the name of the user profile object.
--server Displays details of user sessions matching the SGD server specified. Use the name or a peer DNS name of the SGD server object.
--format Specifies the output format (the default setting is text). Use count to display only the number of matching sessions.

If neither a person nor server is specified, the command lists all user sessions across the array.

Guest users and anonymous users have unique names, even though they can share the same profile in the System Objects organization. To name a guest or anonymous user, use the unique name and not the name of the profile object, for example, .../_dns/newyork.indigo-insurance.com/_anon/1.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example displays details of all user sessions maintained by the SGD server detroit.

tarantella webtopsession list \
  --server "o=Indigo Insurance/cn=detroit"

The following example displays all user sessions across the array.

tarantella webtopsession list

tarantella webtopsession logout

Ends the user session for each person specified. This has the effect of logging them out of their webtop.

Syntax

tarantella webtopsession logout --person pobj...
                               [--format text|quiet]

Description

The following table shows the available options for this command.


Option Description
--person Ends the user session of the specified person. Use the name of the user profile object.
--format Specifies the output format (the default setting is text). With --format quiet, no messages are displayed and the exit code indicates the number of sessions logged out.

You can end user sessions using the following Administration Console tabs:

  • Sessions tab

  • Secure Global Desktop Servers ⇒ User Sessions tab

  • User Sessions tab for a user profile object

Guest users and anonymous users have unique names, even though they can share the same profile in the System Objects organization. To name a guest or anonymous user, use the unique name and not the name of the profile object. For example,.../_dns/newyork.indigo-insurance.com/_anon/1.



Note - Make sure you quote any object names containing spaces, for example, "o=Indigo Insurance".



Examples

The following example logs out Emma Rald from her webtop.

tarantella webtopsession logout \
  --person "o=Indigo Insurance/ou=Marketing/cn=Emma Rald"

The following example ends an anonymous user’s user session.

tarantella webtopsession logout \
  --person .../_dns/newyork.indigo-insurance.com/_anon/1