APPX Login Manager For Windows

This page describes how to install the APPX Login Manager command and how to use it to install, configure, and manage APPX Login Services on Windows.

The APPX Login Manager command is used to configure and manage APPX Login Services.

An APPX Login Service listens for and processes login requests from various types of APPX clients.

The following types of remote APPX clients are supported:

• APPX Desktop Client (Java)
• Windows Client (Win32)
• Character mode client (Unix/Linux Curses)
• APPX ODBC connections (Windows Desktop)
• APPX/Net connections

Options and Features Include:

• User Authentication
  • O/S Authentication
  • HT Authentication
  • APPX Authentication
• User & Group Impersonation (Unix/Linux only)
• SSL Support
  • Anonymous
  • Server Certificates
  • Client Certificates
• Environment Specification
  • Inherit from service
  • Explicitly specified
• umask Specification
• APPX Startup Process
  • Service configuration
  • Client request

Installing the APPX Login Manager Command ( appxLoginMgr)

The APPX Login Manager ( appxLoginMgr) command is installed automatically when you install APPX on your system, there is nothing additional that you need to do to install the appxLoginMgr command. As part of installing APPX, you are given the opportunity to start the connection service. If you did not do this, then you will need to run the appxLoginMgr command to configure and start an instance of the APPX Connection Service before any remote client connections may be established.

The appxLoginMgr command is installed into the "services" subdirectory of the directory where you installed APPX. So, if you installed APPX in "c:\APPX", the full pathname of the appxLoginMgr command will be "C:\APPX\services\appxLoginMgr".

Creating and Configuring an APPX Connection Service

An instance of the APPX Connection Service is initially created, configured, and started by running the appxLoginMgr command with the -install option. At least one appropriately configured instance of the APPX Connection Service must be created, configured, and started before a remote APPX Client can initiate an APPX session. You may create, configure, and start as many different instances of the APPX Connection Service as you desire. However, each concurrently running instance must be configured to listen for connection requests on a different TCP/IP port.

Creating a Connection Service

Before remote clients can connect to an APPX system, at least one instance of an APPX Connection Service must be configured and started.

The -install option of the appxLoginMgr command is used to initially create, configure, and start an instance of the APPX Connection Service. The following steps are performed:

1. A Windows Service is created
2. Registry entries are added for the initialization and environment settings
3. The service is started

The Name of the Service

Each instance of an APPX Connection Service must have a unique name. When creating an instance of a service, the -name option may be used to specify the name that you want the service to have. If you do not specify a name, a name will be assigned for you for example, appx-8060.

TCP/IP Port Number

W hen creating an instance of an APPX Connection Service, the -SockPort option must be used to specify the TCP/IP port number on which the service is to listen for connection requests. Any available TCP/IP port number may be specified when installing an instance of the APPX Login Manager Service. However, as a matter of convention, most APPX administrators configure the APPX Connection Service to listen for connections on port 8060. If additional instances of the APPX Login Manager are configured, each instance is typically assigned the next available port number after 8060.

Changing a Connection Service

Two methods are available for modifying an existing instance of an APPX Connection Service.

Method 1 - The APPX Login Manager Command (appxLoginMgr)

The -modify command and the - replace command of the appxLoginMgr tool can be used to modify or replace a previously configured instance of the APPX Login Manager. These options update the existing APPX Login Manager service with the options specified. If you use this technique, the service will be automatically restarted for you, using the new settings. Note that when specifying variables on the command line, you must prefix them with a dash if you are referring to settings such as SSLmode, or without a dash if you are referring to environment variables, such as APPX_KEYMAP.

Method 2 - Direct Editing of the Registry

The service is created under the key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\<service name>. You can use 'regedit' to change the configuration or environment settings. Note that you will have to manually restart the service for the changes to take affect. Due to the risk inherent in directly changing the registry we recommend using method 1 above.

Managing an APPX Login Manager Service

Two methods are available for managing an existing instance of the APPX Connection Service.

Method 1 - appxLoginMgr command

The appxLoginMgr command can be used to manage an instance of the APPX Connection Service. The appxLoginMgr command can be used to start, stop, restart, or display the status of an instance of an APPX Connection Service.

Method 2 - O/S Services

The Windows Control panel can also be used to manage the APPX Connection Service, just like any other Windows service.

Usage (appxLoginMgr)

Synopsis - Service Configuration

The appxLoginMgr service configuration commands are used to create, configure, and remove an instance of an APPX Connection Service.

appxLoginMgr -install -SockPort=[TCP-Port] [options]... [VARIABLE=VALUE]...

appxLoginMgr -modify -serviceName=SERVICENAME [options]... [VARIABLE=VALUE]...

appxLoginMgr -replace -serviceName=SERVICENAME [options]... [VARIABLE=VALUE]...

appxLoginMgr -remove -serviceName=SERVICENAME

Configuration - Commands

-install -name=SERVICENAME [options]... [VARIABLE=VALUE]...

-install -port=PORT [options]... [VARIABLE=VALUE]...

The -install command is used to configure a new instance of an APPX Connection Service. Either form of the install command may be used.

The first form of the -install command requires only that a service name be specified. All other options are optional including the TCP/IP port. Any option not specified will be configured with an appropriate default value.

The second form of the -install command requires only that a TCP/IP port be specified. All other options are optional including the <nop>ServiceName. Any option not specified will be configured with an appropriate default value.

Both forms of the -install command allow additional configuration options to be specified.

Both forms of the -install command optionally allow values to be specified for environment variables. The environment variables in the environment configuration file will be set for any APPX sessions which are started by the connection service.

In addition to creating the service configuration file and the environment configuration file, the -install command also creates an operating system service that will be automatically started when the computer system is started.

After creating the configuration files and the operating system service, the -install command starts the service.

-modify -name=SERVICENAME [options]... [VARIABLE=VALUE]...

The -modify command is used to modify the configuration of an existing Connection Service. The specified options will be updated in the service configuration files. Any options not specified will not be changed. After updating the configuration files, the -modify command restarts the service.

Note that when specifying variables on the command line, you must prefix them with a dash if you are referring to settings such as SSLmode, or without a dash if you are referring to environment variables, such as APPX_KEYMAP.

-replace -name=SERVICENAME [options]... [VARIABLE=VALUE]...

The -replace command is used to replace an existing Connection Service with a new Connection Service with the same name. The -replace command is effectively the same as a -remove command followed by an -install command. After updating the configuration files, the -replace command restarts the service. Note that when specifying variables on the command line, you must prefix them with a dash if you are referring to settings such as SSLmode, or without a dash if you are referring to environment variables, such as APPX_KEYMAP.

-remove -name=SERVICENAME

The -remove command is used to remove an existing Connection Service. The -remove command will remove the registry entries and the corresponding operating system service. If the service is running when the -remove command is executed, the -remove command will first stop the service and then remove the service.

Configuration - Options

Options - General

-name, -ServiceName=SERVICENAME

The <nop>ServiceName uniquely identifies an APPX connection service. When creating (installing) a connection service, the SERVICENAME value may be any string value that conforms to the rules for valid filenames on your server. If this option is omitted when a connection service is being created, the connection service will be created with a default <nop>ServiceName based on the following template: "appxd-" followed by the specified TCP/IP port number, e.g. "appx-8060".

-DisplayName=DISPLAYNAME

The <nop>DisplayName is a "user-friendly" descriptive name for a connection service. The DISPLAYNAME value will appear in your system's Services control panel. If you don't specify a DISPLAYNAME when a connection service is being created, the connection service will be created with a DISPLAYNAME based on the SERVICENAME.

-engine, -AppxExecutable={../appx, PATHNAME}

This option identifies the PATHNAME of the APPX engine that is to be run when initiating an APPX session. If this option is not specified, an absolute pathname derived from the relative path of "../appx" will be used.

-LogDirectory={C:\, LOGDIR}

When the service is started, two log files are created in the LOGDIR directory - a connection service log file (.log) and a status file (.stat). Both log files have the same name as the <nop>ServiceName but one has a file extension of .log and the other has a file extension of .stat. If the <nop>LogDirectory option is not specified, the log files are created in the /tmp directory.

-AM, -AuthenticationMethod={OS-User, Appx-User, HT-User(HTFILENAME)}

This option identifies the method by which the user ID and the password are to be validated when a connection request is received. If 'OS-User' authentication is specified, the user ID and the password are validated by the connection service using the operating system's authentication service. If 'Appx-User' authentication is specified, the user ID and the password are validated by APPX using the user file and auxiliary password which is maintained in APPX System Administration. If 'HT-User(HTFILENAME)' authentication is specified, the user ID and the password are validated by the connection service using the HTFILENAME file, which is maintained with the htpasswd utility. If you specify 'Appx-User' authentication or HT-User authentication, the user being validated does not need an OS user account. If no authentication method is specified, the default authentication method is OS-User.

-ServiceType=Login

The only valid value when configuring a Connection Service is "Login". If this option is not specified, the default value is Login.

-ServiceDisable={true, false}

This option can be used to temporarily disable or "turn off" the connection service. If set to true, the connection service will still run but it will not accept login requests.

-ServiceDisableLogin={true, false}

This option can be used to disable or "turn off" processing of login requests from interactive clients. If set to true, login requests from interactive clients will not be processed.

-ServiceDisableFMS={true, false}

This option can be used to disable or "turn off" processing of connection requests from APPX/Net connections including the Windows APPX/ODBC driver. If set to true, connection requests from APPX/Net clients will not be processed.

-ServiceDisableAppxKeys={true, false}

This option can be used to disable the ability to define an APPX keymap. If set to true, those interactive clients which support the ability to define an APPX keymap will not be allowed to do so.

serverEnableHTTPdebug={true, false}

Normally you can point a browser at the login port & it will display a configuration page. This might be considered a security risk, setting this to a value of 'false' will cause the listener to immediately hang up and recycle to a listening state on an HTTP request without displaying the configuration information.

Options - Startup Process

-ServiceEnableCmds={true, false}

Set this option to true if you want to allow the client to specify a startup process. Set this option to false if you do not want to allow the client to specify a startup process. If set to true, then any APPX startup process that may have been specified by the client will be invoked when the connection with the APPX session is established. If set to true, then any startup process that is specified by the client will take precedence over any startup process that may have been specified in the connection service configuration. If the option is not specified, the default value is true.

-AppxDatabase=DATABASEID

This option must be specified if the connection service is being configured to invoke a specific startup process when a client session is initiated. If specified, the DATABASEID must be valid, i.e. it must be defined in the Databases file in APPX System Administration.

-AppxApplication=APPLICATIONID

This option must be specified if the connection service is being configured to invoke a specific startup process when a client session is initiated. If specified, the APPLICATIONID must be valid, i.e. it must be defined in the Applications file in APPX System Administration. The specified APPLICATIONID must also be identified in APPX System Administration as a related application for the specified DATABASEID.

-AppxProcessType={Menu, Job, Input, Output, Update, Action, Inquiry, Query, Status, Subroutine}

This option must be specified if the connection service is being configured to invoke a specific startup process when a client session is initiated. This option identifies the type of process that is to be invoked when a client session is initiated.

-AppxProcessName=PROCESSNAME

This option must be specified if the connection service is being configured to invoke a specific startup process when a client session is initiated. This option identifies the name of the process that is to be invoked when a client session is initiated. The PROCESSNAME must be of the type specified and must be defined in the specified APPX Application.

Options - TCP/IP

-port, -SockPort={8060, PORT}

Configure the service to listen for connection requests on the specified TCP/IP PORT number. This option is required with the -install option. You may choose any TCP/IP PORT number that is not reserved or already being used on your system.

-TCPNoDelay={true, false}

This option is used to tune the network performance of the APPX session. When set to true, TCP will send partially filled packets of data rather than wait for a packet to fill before sending it. This can result in improved interactive response time for the APPX session but will likely increase the number of data packets being transmitted over the network.

-TCPEnableKeepAlive={true, false}

Set this option to true if you want an APPX session to be able to detect that the connection between an APPX session and an APPX client has been lost. If this option is set to true and an APPX session has been waiting for a response from an APPX client for the length of time specified by <nop>TCPKeepIdle, then the APPX session will attempt to contact the APPX client to see if it can still be reached. If the APPX client cannot be contacted, then the APPX session will attempt to contact the APPX client every <nop>TCPKeepInterval seconds up to <nop>TCPKeepCount times. After <nop>TCPKeepCount attempts, if the APPX client is unable to be contacted, then the APPX session terminates.

-TCPKeepIdle={300, SECONDS}

This option is used to set the number of seconds that an APPX session is to wait for a response from an APPX client before checking to see if the client can still be contacted.

-TCPKeepCount={8, COUNT}

This option is used to set the number of times that an APPX session is to attempt to contact a non-responsive APPX client before the APPX session should terminate.

-TCPKeepInterval={60, SECONDS}

This option is used to set the number of seconds that an APPX session is to wait between attempts to contact a non-responsive APPX client.

Options - SSL

-SSLMode={optional, required, disabled}

This option is used to control whether or not APPX clients must use SSL connections.

optional - APPX clients may request either an SSL connection or a plain text connection

required - APPX clients must request an SSL connection

disabled - APPX clients may only request a plain text connection

-TrustedCAFile=CAFILENAME

This option identifies the pathname of the file that identifies which client certificates to trust (leave blank if client certificates are not required).

-ServerCertificateFile=CERTFILENAME

This option identifies the pathname of the server's X509 certificate (leave blank for anonymous connections).

-ServerPrivateKeyFile=KEYFILENAME

This option identifies the pathname of server's private key file (unlocks the <nop>ServerCertificateFile).

-UseOldSSLcert={true,false}

Forces the login manager to use pre 5.4.4 certificates. This allows older clients to connect to 5.4.4 and up (5.4.4 & up login manager only).

Configuration - Environment Variables

VARIABLE=VALUE

You can include a space-separated list of environment variables at the end of the command line when you use the -install option. These environment variables will be saved in the env file that is created and will be given to the environment of the appx sessions that are started by the Login Manager. Note that when specifying variables on the command line, you do not prefix them with a dash if you are referring to environment variables.

Synopsis - Service Management

appxLoginMgr [-start | -stop | -restart | -status] {SERVICENAME | -serviceName=SERVICENAME}

MANAGEMENT OPTIONS

-start | < blank >

Start an instance of the Login Manager service using the configuration information in the registry.

-stop

Stop the instance of the Login Manager service.

-restart

Restart (stop and then start) the instance of the Login Manager.

-status

Report the status of all instances of all configured Login Managers.

EXAMPLES

Configure and start a new instance of the Connection Service that will listen for connection requests on port 8060:

appxLoginMgr -install -port=8060 -name=appx8060 -displayName="Appx-Production(8060)" -engine=C:\appx\appx.exe APPXPATH=c:\appx\data APPX_KEYMAP=WINDOWS

Display the status of all Connection Services:

appxLoginMgr -status

Shutdown a running instance of the Connection Service:

appxLoginMgr -stop appx8060

Start a previously configured instance of the Connection Service:

appxLoginMgr -start appx8060

Modify a setting and an environment variable of an existing service

appxLoginMgr -modify -name=appx8060 -SSLMode=required APPX_KEYMAP=Windows

The Log File (log)

If you set -CreateLogFile = true then when an APPX Connection Service is started, a log file is created in the specified <nop>LogDirectory. If a <nop>LogDirectory was not specified, then the log file is created in the C:\ directory.

The name of the log file is the concatenation of the service name and ".log". For example, if the service name is "appxd-8430", the name of the log file will be "appxd-8430.log".

When the connection service is started, the log file is initialized with the configuration of the connection service. The configuration information is followed by a dialog of messages relating to actions performed by the connection service. Each time the connection service processes a connection request, messages relating to the connection request are appended to the log file.

*Daemonize = true
*DontForkEngine = false
*InitScriptStyle = 
*SleepAfterFork = 
AppxApplication = 
AppxDatabase = 
AppxExecutable = ../appx
AppxProcessName = 
AppxProcessType = 
AuthenticationMethod = OS-User
DisplayName = appxd-8430
ImpersonateGID = true
ImpersonateGroup = User
ImpersonateUID = true
ImpersonateUser = LogonUser
IncludeSystemEnv = true
LogDirectory = /tmp
LogNamePattern = /tmp/appxlog%N.xml
LogRotationInterval = 86400
LogRotationSize = 1G
RequireSSL = false
RequireSSLClientCertificates = false
ServerCertificateFile = 
ServerPrivateKeyFile = 
ServerPrivateKeyPassphrase = 
ServiceDisable = false
ServiceDisableAppxKeys = false
ServiceDisableFMS = false
ServiceDisableLogins = false
ServiceDisableODBC = 
ServiceEnableCmds = true
ServiceName = appxd-8430
ServiceType = login
SockPort = 8430
SSLMode = Optional
TCPEnableKeepAlive = true
TCPKeepCount = 8
TCPKeepIdle = 300
TCPKeepInterval = 60
TCPNoDelay = true
TrustedCAFile = 
Umask = 
createListener complete - listening on port 8430
CAppxD::Run starting
handleClients - starting
handleClients - waiting

Reconnect Feature (5.3 & up)

A new connection manager allows a user to reconnect to dropped sessions.

Overview:

A new connection manager allows a user to reconnect to dropped sessions. This capability will be especially useful after the new HTML client is released and users are connecting from mobile devices.

Usage:

The new connection manager is controlled by the following settings in the service .ini file:

To use the new connection manager, set AppxInterface to 'Pipe'. The normal, default, method is 'Socket', which does not have a reconnect capability. The 'Pipe' connection type creates a Named Pipe connection between the server and the new connection manager. The new connection manager then creates a Socket connection between itself and the client. If the connection is dropped, the new connection manager will end. The server will detect this and go into a 'reconnect' mode and will hold Named Pipes connection open for 'AppxPipeTimeout' minutes. If the user reconnects to the same session id within that time limit, a new connection manager will re-establish the connection to the client. Since the server has been holding the Socket connection open, the user will be able to continue their session.

AppxPipeDir is the folder where the new connection manager will keep the named pipes and other connection related files. This is relative to the 'services' directory.

AppxPipeExe is the name of the new connection manager (appxcomm). On Linux/Unix servers this is relative to the 'services' directory. On Windows servers, this must be the complete path to the 'appxcomm.exe' program (usually found in the 'services' directory).

AppxPipeTimeout is the length of time (in minutes) the new connection manager should hold the session open. After this time has expired, the session will be closed and the user will not be able to reconnect.

Note that even though the new connection manager holds the connection open, any data typed in a field before the user pressed Enter or clicked a button will be lost. For example, if they were entering a name and the connection was lost before they pressed Enter or clicked a button, when they reconnect those characters would be lost.

Reconnecting to a session

The login dialog box has a 'Reconnect Id' field:

To reconnect to a lost sesssion, enter the process id (PID) of the lost session. The PID is normally displayed in the title bar of the client, however, most of us don't pay any attention to it so it's unlikely we'll remember it to reconnect. You can check the client preferences to see what the last PID was. To do this, click the 'Options' tab, then the 'Advanced' button, and look for 'lastPid' in the [LastLogin] section:

An Appx System administrator can connect to another users disconnected session, if they know the PID of the lost session.

In Release 5.4.4, a list of dropped sessions will be displayed automatically, eliminating the need to remember PID's.

PAM Capable (5.3 & Up)

In Release 5.3, PAM capability was added. See Login Manager PAM Capable for more information.

Reconnect Revisited (5.4.4)

To make managing reconnects easier, in 5.4.4 a 'Sessions' button was added to the login dialog box for both APPX Desktop Client and the HTML client. To access the 'Sessions' list, enter your login information as usual and click the 'Sessions' button instead of 'Login'. You can use this even if you have not set up your login manager for reconnections. You won't be able to reconnect to a session, but you will be able to manage other sessions.

You will get a display similar to the following:

The display automatically refreshes every 30 seconds, or you can click 'Refresh' to manually refresh the display. The information on the process currently running is only shown if you have enabled the APPX Monitor (See APPX Monitor for details). If not enabled, those columns will be blank.

If you are an APPX System Administrator, you will see all APPX sessions. If you are not an Administrator, you will only see your own sessions.

New - Starts a new session using your current login information (user, password, server & port).

Attach - This button is only enabled if your login manager has been configured to allow reconnections, in which case the Workstation IDs will be 'PIPE' as in the example above. The second session (on /dev/pts/1) is a character mode session, which you cannot Attach to. If your login manager is not configured for reconnections, then the Workstation ID will be either an IP address (for GUI connections) or a /dev/ address for a character mode connection. Since an APPX System Administrator will see all running sessions, they can Attach to any user's session. A new window will open on the Administrators desktop, and the client window on the users desktop will close (when they attempt to use their session). A non Administrator will only see their own sessions, and therefore can only Attach to their own session.

Kill - This will attempt to cancel the selected session. This will only be successful if you have sufficient O/S permissions to allow it, i.e., you have Administrator level or you are cancelling one of your own sessions. See .UTIL KILL SESSION for more information.

Exit - This will exit the session manager without logging in to APPX.

Comments:

Read what other users have said about this page or add your own comments.

-- Page added by: Steve - 17 Jul 2007