APPX Connection Manager For Unix/Linux

This page describes how to install the APPX Connection Manager command and how to use it to install, configure, and manage APPX Connection Services on Unix/Linux systems.

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

An APPX Connection Services:

  • Listen for a connection request from a remote APPX Client on the designated TCP/IP port;
  • Set the appropriate environment and options
  • Initiate an APPX session for the APPX Client that requested a connection.

APPX Conection Services process connection requests for the following types of remote APPX clients:

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

Options and Features Include:

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

Installing the APPX Connection Manager Command ( appxdsvc)

The APPX Connection Manager ( appxdsvc) command is installed automatically when you install APPX on your system. The installer sets the necessary owner and group permissions for the appxdsvc command.  So, there is nothing additional that you need to do to install the appxdsvc command. However, after you install APPX, you will need to run the appxdsvc command to configure and start an instance of the APPX Connection Service before any remote client connections may be established.

The appxdsvc command is installed into the "tools" subdirectory of the directory where you installed APPX. So, if you installed APPX in "/usr/local/appx", the full pathname of the appxdsvc command will be "/usr/local/appx/tools/appxdsvc".

The appxdsvc command must run with the permissions of the root user.  Therefore, the owner of the appxdsvc command should be the root user and the SUID bit should be set so that the appxdsvc command can be run by users other than root but still be run with the permissions of root.

In the event that it is necessary to reset the permissions on the appxdsvc command, the following commands can be run by the root user to set the necessary owner and group permissions for the appxdsvc command.

cd /usr/local/appx/tools chown root appxdsvc chgrp appxgrp appxdsvc chmod 775 appxdsvc chmod u+s appxdsvc

You can check the permissions of the appxdsvc command by running the following command:

ls -l appxdsvc

The recommended permissions should be as follows:

-rwsrwxr-x 1 root root    636843 Jul 11 07:31 appxdsvc

Creating and Configuring an APPX Connection Service

On Unix/Linux systems, an instance of the APPX Connection Service is initially created, configured, and started by running the appxdsvc 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 appxdsvc command is used to initially create, configure, and start an instance of the APPX Connection Service. The following steps are performed:

  1. A configuration file (ini) is created
  2. An environment file (env) is created
  3. A service is created
  4. The service is started

For compete information on using the -install option of the appxdsvc command, please refer to the usage section of this page.

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.

TCP/IP Port Number

When creating an instance of an APPX Connection Service, the -port 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 Connection 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 intances of the APPX Connection 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 Connection Manager Command (appxdsvc)

The -modify option of the appxdsvc command can be used to replace a previously configured instance of the APPX Connection Service. This option replaces the existing APPX Connection Service configuration files (ini and env) with two new files configured as specified.

Method 2 - Text Editor

A text editor can be used to directly edit the APPX Connection Service configuration files (ini and env). The configuration files include comments to help you make the desired changes.

Managing an APPX Connection Service

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

Method 1 - appxdsvc command

The appxdsvc command can be used to manage an instance of the APPX Connection Service. The appxdsvc 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

Your operating system includes commands or programs that can be used to manage services. APPX Connection Services can be managed with these tools. The actual commands and programs vary depending on your operating system.

Usage (appxdsvc)

Synopsis - Service Configuration

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

appxdsvc -install -serviceName=SERVICENAME [options]... [VARIABLE=VALUE]...

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

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

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

appxdsvc -remove -serviceName=SERVICENAME

Configuration - Commands 

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

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

The install command is used to configure and start 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.

The second form of the install command requires only that a TCP/IP port be specified.

Both forms of the install command allow for configuration options to be specified. If specified, the configuration options are stored in the service configuration file (ini). Default values will be used for any configuration options that are not specified including the service name.

Both forms of the install command optionally allow values to be specified for environment variables. If specified, the environment variables and their values are stored in the environment configuration file (env). The environment variables in the environment configuration file will be set for any APPX sessions which are started by the connection 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.

-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 option is effectively the same as a remove command followed by an install command.

-remove -servicename=SERVICENAME

The remove command is used to remove an existing Connection Service. The remove command will remove the configuration files (ini and env) and the corresponding operating system service.

Configuration - Options

Options - General
-name, -ServiceName=SERVICENAME
The 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 ServiceName  based on the TCP/IP port number that was specified: "appxd" followed by a "-" and the specified port number, e.g "appxd-8060".

-DisplayName=DISPLAYNAME

The DisplayName is a "user-friendly" descriptive name for a connection service.  The DISPLAYNAME value will appear in your system's Services control panel and will be displayed by the ps command.  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}

The APPX engine at the specified PATHNAME will be run when initiating an APPX session. The specified PATHNAME may be alsolute or it may be relative to the location of the appxdsvc command

-LogDirectory={/tmp, LOGDIR}

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

Acceptable values are 'OS-User', 'Appx-User', and 'HT-User(HTFILENAME)'. With 'Appx-User' authentication, passwords are validated against the Appx user file With 'OS-User' authentication, passwords are validated by the operating system. With 'HT-User(filename)' authentication, passwords are validated against the named file (which you can maintain the Apache's htpasswd utility. If you choose 'Appx-User' authentication, you do not need a separate OS user account for each Appx user.  If this option is not specified, the default value 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}

-ServiceDisableLogin={true, false}

-ServiceDisableFMS={true, false}

-ServiceDisableAppxKeys={true, false}

-initScript={lsb, RedHat}

Used with -install option to specify the type of operating system that the service script is to be created for. If this option is not specified, appxdsvc will determine which type of service script to install.
Options - Session Identity/Permissions
-ImpersonateUID={true, false}
If this value is set to false, an APPX session which is initiated by the connection service will run as the user of the connection service.  Set this value to true if you want the APPX session to run with the permissions of a user (impersonate) other than the user of the connection service.  If this value is set to true, then the ImpersonateUser option determines which user the APPX session should impersonate.

-ImpersonateUser={LogonUser, NamedUser(USERID), ServiceOwner}

This option determines which O/S user the APPX session should impersonate (run as).

If LogonUser is specified, the user ID of the APPX session will be set to the user ID that was provided by the client login.  This user ID must be a valid O/S user.  The connection service must be running with the permissions of the root user if the LogonUser option is specified.

If NamedUser is specifed, the user ID of the APPX session will be set to the specified USERID.  This USERID must be a valid O/S user.  The connection service must be running with the permissions of the root user if the NamedUser option is specified.

If ServiceOwner is specified, the user ID of the APPX session will be the user ID that the connection service is running as.

-ImpersonateGID={true, false}

-ImpersonateGroup={User, LogonUser, LogonGroup, NamedGroup(groupname), ServiceOwner, ServiceGroup}

-Umask=FILECREATIONMASK

APPX sessions which are initiated by the connection service will be given the specified FILECREATIONMASK.  The FILECREATIONMASK is used to set the permissions on files that are created by the APPX session.  The FILECREATIONMASK value should be a 4-digit octal value representing a standard Unix/Linux umask value.  For more information on umask values, please refer to your Unix/Linux system documentation.

-IncludeSystemEnv={true, false}

Set this option to true if you want the APPX sessions which are initiated by the connection service to inherit the environment of the connection service.
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}

-TCPEnableKeepAlive={true, false}

-TCPKeepIdle={300, SECONDS}

-TCPKeepCount={8, COUNT}

-TCPKeepInterval={60, SECONDS}

Options - SSL
-SSLMode={optional, required, disabled}

-RequireSSL={true, false}

-RequireSSLClientCertificates={true, false}

-ServerCertificateFile=CERTFILENAME

-ServerPrivateKeyFile=KEYFILENAME

-ServerPrivateKeyPassphrase=PASSPHRASE

-TrustedCAFile=CAFILENAME

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 Connection Manager.

Synopsis - Service Management

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

MANAGEMENT OPTIONS

-start | < blank >
Start an instance of the Connection Manager service using the configuration information in the SERVICENAME.ini and the SERVICENAME.env files.

-stop

Stop the instance of the Connection Manager service that was started with the SERVICENAME.ini file.

-restart

Restart (stop and then start) the instance of the Connection Manager that was started with the SERVICENAME.ini file.

-status

Report the status of the instance of the Connection Manager that was started with the SERVICENAME.ini file.

EXAMPLES

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

appxdsvc -install -port=8060

Warning - the engine that you named has the setuid bit enabled
you may not want that bit set for the authentication method that you have chosen (OS-User)
To turn off the setuid bit, chmod u-s
../appx Configuration written to: appxd-8060.ini
Environment written to: appxd-8060.env
Service script written to: /etc/rc.d/init.d/appxd-8060
appxdsvc -install -port=8060 -name=appx8060 -displayName="Appx-Production(8060)" -engine=/usr/local/appx/appx APPXPATH=c:\appx\data APPX_KEYMAP=WINDOWS

Display the status of an instance of the Connection Service:

appxdsvc -status appx8060

Shutdown a running instance of the Connection Service:

appxdsvc -stop appx8060

Start a previously configured instance of the Connection Service:

appxdsvc -start appx8060

The Configuration File (ini)

Each instance of an APPX Connection Service has a configuration file that is used to store the various parameters relating to that specific instance of the connection service.

The -install option of the appxdsvc command creates the configuration file when the service is created.

The name of the configuration file is the concatenation of the service name and ".ini".  For example, if the service name is "appxd-8060", the name of the configuration file will be "appxd-8060.ini".

The configuration file is created in whichever directory is your current directory at the time that the appxdsvc command is run to create the service. Therefore, before you run the appxdsvc command to create a service, you must first change to the directory where you want the configuration file to reside. For example, if you want the configuration file to be created in the APPX tools directory, you should change to the tools directory before you run the appxdsvc command.

The name of the configuration file and the location of the configuration file should not be changed.  The service that is created will not work correctly if the name or the location of the configuration file is changed.

# Appx connection manager configuration file
#
#   You can change this file by hand, or
#   use the uappxd program for better results
#
#   blank lines are ignored
#
#   anything following a '#' is treated as a comment
#
#   case is not important on the left-hand side
#   properties whose descriptions end in a '?' are
#   boolean and should be set to true or false
# --------------------------------------------------
# AppxApplication         =                     #startup application for spawned engines
# AppxDatabase            =                     #startup database for spawned engines
AppxExecutable            = /usr/local/appx/appx    #pathname to Appx engine
# AppxProcessName         =                     #startup process name for spawned engines
# AppxProcessType         =                     #startup process type for spawned engines
AuthenticationMethod      = OS-User             #authentication method (OS-User, Appx-User, HT-User(filename))
DisplayName               = Login-8430          #descriptive name
ImpersonateGID            = true                #change effective grouo ID for spawned engines?
ImpersonateGroup          = NamedGroup(appxgrp) #[LogonUser, NamedGroup(groupname), ServiceOwner]
ImpersonateUID            = true                #change effective user ID for spawned engines?
ImpersonateUser           = NamedUser(appx)     #[LogonUser, NamedUser(username), ServiceOwner]
# IncludeSystemEnv        = true                #include service environment variables in spawned engines?
# LogDirectory            = /tmp                #directory where log file should reside
# LogNamePattern          = /tmp/appxlog%N.xml  #audit log filename pattern (see man strftime for details
# LogRotationInterval     = 86400               #number of seconds between audit log rotations
# LogRotationSize         = 1G                  #maximum audit log file size
# RequireSSL              = false               #Require SSL-secured connections?
# RequireSSLClientCertificates = false          #require SSL-client certificates?
# ServerCertificateFile   =                     #pathname of server's X509 certificate (leave blank for anonymous connections
# ServerPrivateKeyFile    =                     #pathname of server's private key file (unlocks the ServerCertificateFile)
# ServerPrivateKeyPassphrase =                  #passphrase that unlocks ServerPrivateKeyFile
# ServiceDisable          = false               #disable this service?
# ServiceDisableAppxKeys  = false               #disable keyboard mapping?
# ServiceDisableFMS       = false               #disable AppxNET connections?
# ServiceDisableLogins    = false               #disable interactive logins?
# ServiceEnableCmds       = true                #allow client-side startup options?
ServiceName               = appxd-8430          #name of service
ServiceType               = login               #service type (login or logmonitor)
SockPort                  = 8430                #port number to service
# SSLMode                 = optional            #SSL connection type (optional, required, disabled)
# TCPEnableKeepAlive      = true                #Enable TCP dead-connection detection
# TCPKeepCount            = 8                   #Maximum number of keep-alive pings
# TCPKeepIdle             = 300                 #Idle time before ping sent to client (in seconds)
# TCPKeepInterval         = 60                  #Interval between keep-alive pings
# TCPNoDelay              = true                #disable TCP packet filling delay?
# TrustedCAFile           =                     #determines which client certificates to trust
# Umask                   =                     #umask (file creation mask) given to spawned engines

The Environment File (env)

Each instance of an APPX Connection Service has an environment file that is used to store the environment variables relating to that specific instance of the connection service.  The environment variables in the environment file are inherited by each APPX session that is started by the APPX Connection Service.

The -install option of the appxdsvc command creates the environment file when the service is created.

The name of the environment file is the concatenation of the service name and ".env".  For example, if the service name is "appxd-8060", the name of the environment file will be "appxd-8060.env".

The environment file is created in whichever directory is your current directory at the time that the appxdsvc command is run to create the service. Therefore, before you run the appxdsvc command to create a service, you must first change to the directory where you want the environment file to reside. For example, if you want the environment file to be created in the APPX tools directory, you should change to the tools directory before you run the appxdsvc command.

The name of the environment file and the location of the environment file should not be changed.  The service that is created will not work correctly if the name or the location of the environment file is changed.

# Appx connection manager environment variables
#
#   The entries in this file will become
#   environment variables in the engines
#   spawned by this service
#
#   blank lines are ignored
#
#   anything following a '#' is treated as a comment
#
#   letter case IS important in this file
# --------------------------------------------------
APPX_KEYMAP=WINDOWS

Comments:

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



-- Page added by: Steve - 17 Jul 2007

Edit | Attach | Watch | Print version | History: r68 | r27 < r26 < r25 < r24 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r25 - 2007-08-16 - SteveFrizzell
 
  • Edit
  • Attach
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback