Create a Direct Connection shortcut

This procedure guides you through the process of creating a Direct Connection Shortcut using the Shortcut Wizard.

To open the Shortcut Wizard, in the Shortcuts window, click the New... button.

A direct connection is a connection that is established through terminal emulation.

Shortcut Wizard page 1: Shortcut identification and Connection type

  1. Complete the fields of the Shortcut identification section:
    1. In the Name field, provide a name for the shortcut.
    2. Optional: In the Icon field, provide a file name that will be used to display an icon associated with this shortcut.
    3. Optional: If you want to store the shortcut locally for the current user, select the Store shortcut in settings checkbox.
      By default, shortcuts are saved in the &AppDataDir/config.xml file (see GDC configuration file directories for more information). Shortcuts written to this file are shared amongst all users who use this installation of the GDC. Selecting the Store shortcut in settings option is useful when the GDC is on a shared network drive and you do not want the current user to modify the common shortcuts.
      Note: When the config.xml file is read-only, the Store shortcut in settings checkbox is selected by default and you do not have the option to deselect it.
      Note: Any modification to a non-local shortcut displays a warning and creates a local copy of the shortcut.
  2. In the Connection type section, select the Direct, connection is established through terminal emulation and click Next.

Shortcut Wizard page 2: Host information

  1. In the Name field, enter the hostname where the Runtime System is hosted. This can be omitted if you use the -Host or -H command line option.
  2. In the Command field, enter the command line that will be executed to start the application on the Runtime System side and click Next.

    Within the command line, you can use the following tags:

    Table 1. Tags for use at the command line
    Tag Replaced by
    @FGL FGLSERVER=<IP Address>:<serv num> export FGLSERVER; FGLGUI=1; export FGLGUI
    Note: Additional environment variables are set to assist with the security key mechanism. See Security levels.

    The command to start the demo application using the @FGL tag would be "@FGL; fglrun demo".

    Table 2. You can use one of the @FGL variants depending on your system
    Tag Replaced by
    @FGLNT set FGLSERVER=<IP Address>:<serv num>&&set FGLGUI=1
    Note: Additional environment variables are set to assist with the security key mechanism. See Security levels.
    @FGLCSH setenv FGLSERVER "<IP Address>:<serv num>";setenv FGLGUI 1
    Note: Additional environment variables are set to assist with the security key mechanism. See Security levels.
    @FGLKSH FGLSERVER="<IP Address>:<serv num>";export FGLSERVER;FGLGUI=1;export FGLGUI
    Note: Additional environment variables are set to assist with the security key mechanism. See Security levels.
    @SRVNUM <GDC listening port - 6400 (The second part of FGLSERVER)>
    @PORT <GDC listening port>
    @USR <Client current user name>
    Note: On Windows® operating systems, @USR uses GetUserNameEx with "NameUserPrincipal" as the first argument and without the "@domain" part of the result string. On non-Windows operating systems, @USR and @LEGACYUSR return the same string.
    @LEGACYUSR <Client current user name>
    Note: On Windows operating systems, @LEGACYUSR uses GetUserName. On non-Windows operating systems, @USR and @LEGACYUSR return the same string.
    Tip: @USR should be used in most cases. @LEGACYUSR exists to handle issues that may arise when migrating to Genero Desktop Client 3.0 from an earlier version.
    @LUSR <Client current user name, lower case version>
    @USER <User name on the remote system>
    @IP <IP address of the client computer>
    @COMPUTER <Machine host name>
    @E_SRV export FGLSERVER
    @4GLSRVVER <GDC version>

    These tags will automatically be replaced when the command is sent to the Runtime System host.

Shortcut Wizard page 3: Terminal protocol and Terminal options

  1. In the Terminal protocol section, select from the list of options and click Next.
    With a direct connection type, the basic mechanism (without any port forwarding configuration) is using 2 connections:
    • From GDC to server: the GDC establishes the connection to a server using either the telnet protocol, the SSH protocol or the SSH2 protocol via the fgltty terminal.
      Tip: The SSH2 protocol is recommended for security purposes.
    • From server to GDC: the server, where the Genero environment is installed, executes a command line which starts the application on the GDC via a TCP/IP network. The IP address of the GDC is retrieved using the FGLSERVER environment variable.
      Note: The telnet, SSH and SSH2 protocols are only used for establishing the first connection from GDC to server.
    Using SSH or SSH2, port forwarding can be established to secure your connection. When you use this option, a SSH tunnel is created. This means that, in opposition with the basic mechanism without port forwarding, there are no longer two connections, but a single connection: when the server establishes the connection to the client, it can use the existing SSH connection to tunnel the graphical connection.
    Note: While GDC 3.00 supports IPv6, as DVM does not support IPv6, you cannot launch an application on a distant host with a GDC listening using a direct connection.
  2. In the Terminal options section, choose any of the available options and click Next.

    The Backspace key sends Control-H option modifies the sequence sent by the backspace key in FGLTTY. By default, Control-?(127) is used but you may change it to Control-H. This will allow you, for instance, to use the backspace key in dbaccess.

    If Show terminal window is checked, the window of FGLTTY, our Emulation Terminal Utility, will be visible. (Please refer to the Terminals section). This could help you check whether your command line is valid.

    The Start command in a new shell option allows you to start a regular shell session before executing the remote host command.
    Note: This option is mandatory when using Automatic port forwarding, which can be selected in step 4.

Shortcut Wizard page 4: Port forwarding mode

  1. Select the port forwarding method you want from the list and click Next.
    The following port forwarding options are available:
    • If you select Disabled, port forwarding is disabled.
    • If you select Automatic, the option to edit the Port range is provided.
    • If you select Fixed port, you must enter the port that you want to be used.
    • If you select Command line port request, you must enter the command to be executed on the remote host.
      Note: The command must display a string in the form of port=xxx.
    • If you select HTTP port request, you must enter the URL that you want to open for port forwarding port resolution.
      Note: The URL body must include a terminal string in the format of port=xxx.

Shortcut Wizard page 5: Login form and Authentication method

  1. In the Login form section, enter a filepath in the Form file field.

    To use your own login form, specify the login form file to use. The form file must be a .ui file, which is a Qt designer's file format. See Customizing your own login form. Check Always on Top to force the login form to always display on top.

  2. Choose you Authentication method and click Next.
    The Authentication method will either be Standard or Kerberos.
    • The Standard authentication method:

      In the User field, provide the username you are using to connect to the host. This can be omitted if you use the -User or -U command line option.

      If Password required is checked, GDC will ask you for a password. If your configuration allows you to connect without a password, uncheck this option. If a password is still requested, review your configuration.

      Important: GDC will not modify your configuration to allow you to connect without a password. It is up to you or your administrator to manage this.
      The next two options concern the keeping of the password:
      • If Keep password is checked, GDC keeps in memory the password you enter the first time you start a shortcut, and reuses the password when you restart. The password is stored for the session; it is kept in memory and is lost if you stop the GDC. The password is kept in memory while GDC is launched and automatically completed in the password field, but it is forgotten once GDC is stopped.
      • If Allow persistent save is checked, GDC keeps the password between sessions. The GDC can be stopped and re-started, and the password is maintained. This option is only enabled if the Keep password option is checked.
        Important: GDC never stores your password in a file or elsewhere unless Allow persistent save is checked. GDC stores your password on disk in an encrypted form which is very difficult to read but not impossible. Someone with strong knowledge in cryptology can eventually break the password protection.
      The next two options involve the display of the login form:
      • If Don't ask again is checked, GDC only displays the login box to ask for the password the first time a shortcut is launched. After that, the password will be silently sent without bothering the user with another login box, for the duration of the GDC session.
      • If Even after restart is checked, the GDC uses the saved password (see Allow persistent save) to silently send the password in subsequent sessions; the password field is no longer displayed, even after the GDC is restarted. This option is only enabled if both Allow persistent save and Don't ask again are checked.

      If any of those options save a password, it will be stored until manually cleared.

      The SSH key file field: If you use an SSH connection, you can specify an ssh key file that contains the login information. The file format must use the PuTTY format and can be generated using PuTTY tools.

    • The Kerberos authentication method:

      On Windows platforms ( all versions after Windows 2000 ) you can also use Kerberos authentication if your user and computer are registered on an ActiveDirectory that provides a Kerberos interface. Using this authentication method, you are free to Allow Ticket Forwarding; this allows the SSH server to forward the Kerberos ticket that identifies the user to other processes. You may also select a Server realm; this identifies the Kerberos domain. This field can be mandatory, depending on the ActiveDirectory / Kerberos server configuration. Ask your System administrator for further details.

Shortcut Wizard page 6: Terminal strings

  1. Specify the connection strings settings and click Next.
    On this page, the wizard allows you to specify connection strings. A table shows a default set of connection string/action items. Defining strings with associated actions configures the GDC with actions to take when the runtime system host displays a given string on the terminal. For a given string the GDC can perform one of the following actions:
    • Ask the user for a value, and send it back
    • Display a message to the user
    • Ask for a password
    • Send the shortcut password
    • Send the shortcut command
    • Execute a local command and send the result
    • Return a defined string
    • Ignore the Runtime System string
    • Send the login
    • Get a free port number for Port Forwarding
    • Show or hide the terminal
    • End the terminal
    Tip: You can select these actions from the drop-down menu in the row under the Action column. You can also define new strings and associate them with appropriate actions by clicking New.

    The default terminal strings should be suitable in most cases, but you may have to adapt them to your system. For instance, the default string to send the command that is last login: may be different on your server.

    You can specify whether each string should be recognized only once or every time (check only once).

    When the Ignore remaining strings option is allowed and is checked for a string, the rest of the strings that appear in the list below it are ignored. For example, if Ignore remaining strings is checked for password, and the string is parsed from the terminal output, then strings defined below it in the list will not be searched in the terminal output anymore (regardless of any option defined for those strings in the shortcut wizard).

    Table 3. Connection string examples
    Recognized string Description Action performed by GDC
    password: This is the string used by the telnet daemon to ask for the password. Sends the password
    last login: This is the string used by the telnet daemon to tell the user he has logged in successfully. Sends the command
    login: This is the string displayed by the telnet daemon when the login has failed. Displays a message "Authentication has failed"

    Please contact your System administrator if the default values are not appropriate.

Shortcut Wizard page 7: Fgltty Configuration

  1. Configure your Fgltty settings and click Finish to complete the setup and exit the Shortcut Wizard.

    Starting with Genero 2.30, these options are inherited from PuTTY. If you need more details on these options, please consult the PuTTY documentation.