Tags:
view all tags
---+ 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._ %TOC% The APPX Connection Manager command is used to configure and manage APPX Connection Services. An APPX Connection Service listens for and processes connection 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 Certficates * Client Certificates * Environment Specification * Inherit from service * Explicitly specified * umask Specification * APPX Startup Process * Service configuration * Client request ---++ Installing the APPX Connection Manager Command ( _appxloginmgr_) The APPX Login Manager ( _appxloginmgr_) command is installed automatically when you install APPX on your system. The installer sets the necessary owner and group permissions for the appxloginmgr command. So, there is nothing additional that you need to do to install the appxloginmgr command. However, after you install APPX, 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 "tools" subdirectory of the directory where you installed APPX. So, if you installed APPX in "/usr/local/appx", the full pathname of the appxloginmgr command will be "/usr/local/appx/tools/appxloginmgr". The appxloginmgr command must run with the permissions of the root user. Therefore, the owner of the appxloginmgr command should be the root user and the SUID bit should be set so that the appxloginmgr 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 appxloginmgr command, the following commands can be run by the root user to set the necessary owner and group permissions for the appxloginmgr command. <pre> <p /><strong>cd /usr/local/appx/tools</strong> <strong>chown root appxloginmgr</strong> <strong>chgrp appxgrp appxloginmgr</strong> <strong>chmod 4775 appxloginmgr</strong> </pre> You can check the permissions of the appxloginmgr command by running the following command: <pre> <strong>ls -l appxloginmgr</strong> </pre> The recommended permissions should be as follows: <pre> -rwsrwxr-x 1 root root 636843 Jul 11 07:31 appxloginmgr </pre> ---++ 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 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 configuration file (ini) is created 1 An environment file (env) is created 1 A service is created 1 The service is started For compete information on using the -install option of the appxloginmgr command, please [[APPXConnectionManagerForUnixLinux#Usage_appxdsvc][refer to the usage section ]]of this page. <blockquote style="margin-right: 0px;" dir="ltr"> ---++++ 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. </blockquote> ---+++ Changing a Connection Service Two methods are available for modifying an existing instance of an APPX Connection Service. <blockquote style="margin-right: 0px;" dir="ltr"> ---++++ Method 1 - The Connection Manager Command (appxdsvc) The __-modify__ command and the - __replace__ command of the appxdsvc connection manager can be used to modify or replace a previously configured instance of the APPX Connection Service. These options update the existing APPX Connection Service configuration files (ini and env) with the options 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. If you use this method to modify an existing configuration, you should exercise care to ensure that the syntax is correct. The preferred method for modifying a connection service is with Medhod 1 above.</blockquote> ---++ Managing an APPX Connection Service Two methods are available for managing an existing instance of the APPX Connection Service. <blockquote style="margin-right: 0px;" dir="ltr"> ---+++ 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. </blockquote> ---++ Usage (appxdsvc) <blockquote style="margin-right: 0px;" dir="ltr"> ---+++ Synopsis - Service Configuration <blockquote style="margin-right: 0px;" dir="ltr">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 <blockquote style="margin-right: 0px;" dir="ltr"> *-install* -name=SERVICENAME [options]... [VARIABLE=VALUE]... *-install* -port=PORT [options]... [VARIABLE=VALUE]... <blockquote style="margin-right: 0px;" dir="ltr">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. The configuration options are stored in the service configuration file (ini). 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. 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.</blockquote> *-modify* -name=SERVICENAME [options]... [VARIABLE=VALUE]... <blockquote style="margin-right: 0px;" dir="ltr">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.</blockquote> *-replace* -name=SERVICENAME [options]... [VARIABLE=VALUE]... <blockquote style="margin-right: 0px;" dir="ltr">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.</blockquote> *-remove* -name=SERVICENAME <blockquote style="margin-right: 0px;" dir="ltr">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. If the service is running when the __-remove__ command is executed, the __-remove__ command will first stop the service and then remove the service.</blockquote></blockquote> ---++++ Configuration - Options <blockquote style="margin-right: 0px;" dir="ltr"> ---+++++ Options - General *-name, -ServiceName=SERVICENAME* <blockquote style="margin-right: 0px;" dir="ltr">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 "appxd-8060".</blockquote> *-DisplayName=DISPLAYNAME* <blockquote style="margin-right: 0px;" dir="ltr">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 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. </blockquote> *-engine, -AppxExecutable={<u>../appx</u>, PATHNAME}* <blockquote style="margin-right: 0px;" dir="ltr">This option identifies the PATHNAME of the APPX engine that is to be run when initiating an APPX session. The specified PATHNAME may be alsolute or it may be relative to directory in which the service configuration file (ini) for the connection service is located. If this option is not specified, the default PATHNAME of "../appx" is used to initiate an APPX session.</blockquote> *-LogDirectory={<u>/tmp</u>, LOGDIR}* <blockquote style="margin-right: 0px;" dir="ltr">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.</blockquote> *-AM, -AuthenticationMethod={<u>OS-User</u>, Appx-User, HT-User(HTFILENAME)}* <blockquote style="margin-right: 0px;" dir="ltr">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 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 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 <font color="#000000">is OS-User.</font></blockquote> *-ServiceType=Login* <blockquote style="margin-right: 0px;" dir="ltr">The only valid value when configuring a Connection Service is "Login". If this option is not specified, the default value <font color="#000000">is Login.</font></blockquote> *-ServiceDisable={true, <u>false</u>}* <blockquote style="margin-right: 0px;" dir="ltr">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.</blockquote> *-ServiceDisableLogin={true, <u>false</u>}* <blockquote style="margin-right: 0px;" dir="ltr">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.</blockquote> *-ServiceDisableFMS={true, <u>false</u>}* <blockquote style="margin-right: 0px;" dir="ltr">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.</blockquote> *-ServiceDisableAppxKeys={true, <u>false</u>}* <blockquote style="margin-right: 0px;" dir="ltr">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.</blockquote> *-initScript={lsb, <nop>RedHat}* <blockquote style="margin-right: 0px;" dir="ltr">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.</blockquote> ---+++++ Options - Session Identity/Permissions *-ImpersonateUID={<u>true</u>, false}* <blockquote style="margin-right: 0px;" dir="ltr">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 <nop>ServiceOwner. 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 <nop>ImpersonateUser option determines which user the APPX session should impersonate.</blockquote> *-ImpersonateUser={<u>LogonUser</u>, <nop>NamedUser(USERID), <nop>ServiceOwner}* <blockquote style="margin-right: 0px;" dir="ltr">This option determines which O/S user the APPX session should impersonate (run as). If <nop>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 <nop>LogonUser option is specified. If <nop>NamedUser is specified, 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 <nop>NamedUser option is specified. If <nop>ServiceOwner is specified, the user ID of the APPX session will be the user ID that the connection service is running as.</blockquote> *-ImpersonateGID={<u>true</u>, false}* <blockquote style="margin-right: 0px;" dir="ltr">If this value is set to false, an APPX session which is initiated by the connection service will run with the group permissions of the connection <nop>ServiceOwner. Set this value to true if you want the APPX session to have group permissions based on the <nop>ImpersonateGroup option.</blockquote> *-ImpersonateGroup={<u>User</u>, <nop>LogonUser, <nop>LogonGroup, <nop>NamedGroup(GROUPNAME), <nop>ServiceOwner, <nop>ServiceGroup}* <blockquote style="margin-right: 0px;" dir="ltr">This option determines which group permissions the APPX session should run with. If User is specified, the APPX session will run with the group permissions of the user that the session is running as (impersonating). If <nop>LogonUser or <nop>LogonGroup is specified, the APPX session will run with the group permissions of the user ID that the client provided in conjunction with the connection request. The user ID must be a valid O/S user. If <nop>NamedGroup is specified, the group permissions of the APPX session will be set to the specified GROUPNAME. This GROUPNAME must be a valid O/S group. If <nop>ServiceOwner or <nop>ServiceGroup is specified.</blockquote> *-Umask=FILECREATIONMASK* <blockquote style="margin-right: 0px;" dir="ltr">When a file is created, the default permissions set by Unix/Linux are 666 (-rw-rw-rw-). When a directory is created, the default permissions set by Unix/Linux are 777 (drwxrwxrwx). If the umask option is specified, the FILECREATIONMASK value will modify the default permissions of files or directories that are created by the APPX session. The value of FILECREATIONMASK must be a decimal, hex, or octal number whose bits will be used to mask or turn off the corresonding bits of the default file creation permissions. For example, if you want files to be created with permissions of 644, the appropriate FILECREATIONMASK value would be 022 (octal). If you want files to be created with the default permissions of 666, the appropriate FILECREATIONMASK value would be 000 (octal). For more information on umask values, please refer to your Unix/Linux system documentation. If the umask option is not set, files and directories that are created by the APPX session will be given the default permissions of the Service Owner.</blockquote> *-IncludeSystemEnv={<u>true</u>, false}* <blockquote style="margin-right: 0px;" dir="ltr">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.</blockquote> ---+++++ Options - Startup Process *-ServiceEnableCmds={<u>true</u>, false}* <blockquote style="margin-right: 0px;" dir="ltr">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 <font color="#000000">true</font>, 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<font color="#000000"> true.</font></blockquote> *-AppxDatabase=DATABASEID* <blockquote style="margin-right: 0px;" dir="ltr">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.</blockquote> *-AppxApplication=APPLICATIONID* <blockquote style="margin-right: 0px;" dir="ltr">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.</blockquote> *-AppxProcessType={Menu, Job, Input, Output, Update, Action, Inquiry, Query, Status, Subroutine}* <blockquote style="margin-right: 0px;" dir="ltr">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.</blockquote> *-AppxProcessName=PROCESSNAME* <blockquote style="margin-right: 0px;" dir="ltr">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.</blockquote> ---+++++ Options - TCP/IP *-port, -SockPort={<u>8060</u>, PORT}* <blockquote style="margin-right: 0px;" dir="ltr">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.</blockquote> *-TCPNoDelay={<u>true</u>, false}* <blockquote style="margin-right: 0px;" dir="ltr">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. </blockquote> *-TCPEnableKeepAlive={<u>true</u>, false}* <blockquote style="margin-right: 0px;" dir="ltr">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. </blockquote> *-TCPKeepIdle={<u>300</u>, SECONDS}* <blockquote style="margin-right: 0px;" dir="ltr">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.</blockquote> *-TCPKeepCount={<u>8</u>, COUNT}* <blockquote style="margin-right: 0px;" dir="ltr">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.</blockquote> *-TCPKeepInterval={<u>60</u>, SECONDS}* <blockquote style="margin-right: 0px;" dir="ltr">This option is used to set the number of seconds that an APPX session is to wait between attemps to contact a non-responsive APPX client.</blockquote> ---+++++ Options - SSL *-SSLMode={<u>optional</u>, required, disabled}* <blockquote style="margin-right: 0px;" dir="ltr">This option is used to control whether or not APPX clients must use SSL connections. <blockquote style="margin-right: 0px;" dir="ltr">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</blockquote></blockquote> *-TrustedCAFile=CAFILENAME* <blockquote style="margin-right: 0px;" dir="ltr">This option identifies the pathname of the file that identifies which client certificates to trust.</blockquote> *-ServerCertificateFile=CERTFILENAME* <blockquote style="margin-right: 0px;" dir="ltr">This option identifies the pathname of the server's X509 certificate (leave blank for anonymous connections).</blockquote> *-ServerPrivateKeyFile=KEYFILENAME* <blockquote style="margin-right: 0px;" dir="ltr">This option idenfies the pathname of server's private key file (unlocks the <nop>ServerCertificateFile).</blockquote> *-RequireSSL={true, <u>false</u>}* <blockquote style="margin-right: 0px;" dir="ltr">This option is not needed and has not been implemented.</blockquote> *-RequireSSLClientCertificates={true, <u>false</u>}* <blockquote style="margin-right: 0px;" dir="ltr">This option is not needed and has not been implemented.</blockquote> *-ServerPrivateKeyPassphrase=PASSPHRASE* <blockquote style="margin-right: 0px;" dir="ltr">This option is not needed and has not been implemented.</blockquote></blockquote></blockquote></blockquote> ---++++ Configuration - Environment Variables <blockquote style="margin-right: 0px;" dir="ltr"><u>VARIABLE</u>=<u>VALUE</u> <blockquote style="margin-right: 0px;" dir="ltr">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. </blockquote></blockquote> ---+++ Synopsis - Service Management <blockquote style="margin-right: 0px;" dir="ltr"> *appxdsvc* [-start | -stop | -restart | -status] {SERVICENAME | -serviceName=SERVICENAME} </blockquote> *MANAGEMENT OPTIONS* <blockquote style="margin-right: 0px;" dir="ltr"> *-start* | < _blank_ > <blockquote style="margin-right: 0px;" dir="ltr">Start an instance of the Connection Manager service using the configuration information in the SERVICENAME.ini and the SERVICENAME.env files. </blockquote> *-stop* <blockquote style="margin-right: 0px;" dir="ltr">Stop the instance of the Connection Manager service that was started with the SERVICENAME.ini file. </blockquote> *-restart* <blockquote style="margin-right: 0px;" dir="ltr">Restart (stop and then start) the instance of the Connection Manager that was started with the SERVICENAME.ini file. </blockquote> *-status* <blockquote style="margin-right: 0px;" dir="ltr">Report the status of the instance of the Connection Manager that was started with the SERVICENAME.ini file. </blockquote></blockquote> *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* <blockquote style="margin-right: 0px;" dir="ltr"> <pre> 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.envtten to: /etc/rc.d/init.d/appxd-8060 </pre> *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* </blockquote> ---++ 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-8430", the name of the configuration file will be "appxd-8430.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. <blockquote style="margin-right: 0px;" dir="ltr"> <pre> # 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 </pre> </blockquote> ---++ 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-8430", the name of the environment file will be "appxd-8430.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. <blockquote style="margin-right: 0px;" dir="ltr"> <pre> # 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 </pre> </blockquote> ---++ The Status File (stat) When an APPX Connection Service is started, a status file is created in the specified <nop>LogDirectory. If a <nop>LogDirectory was not specified, then the status file is created in the /tmp directory. The name of the status file is the concatenation of the service name and ".stat". For example, if the service name is "appxd-8430", the name of the status file will be "appxd-8430.stat". The status file can be viewed to see the actual context within which the service is running. <blockquote style="margin-right: 0px;" dir="ltr"> <pre> appxd-8430 running as process 28192 Effective User ID 0 Real User ID 0 Configuration values follow *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 = Environment variables follow APPX_KEYMAP = WINDOWS </pre> </blockquote> ---++ The Log File (log) 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 /tmp 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. <blockquote style="margin-right: 0px;" dir="ltr"> <pre> *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 </pre> </blockquote> ---++ Testing Results ---+++ 001) (Suggestion) Rename uappxd appxLoginMgr ---+++ 002) (Suggestion) Rename uappxd appxAuditLogger ---+++ 003) (Fixed) Bug #2090 Verified as fixed [root@APPX4.30TestBox tools]# ./appxdsvc -remove -name=appxd-8060 Stopping service... stopped Deleting init script... done Deleting configuration files... done Finished [root@APPX4.30TestBox tools]# cd /etc/init.d [root@APPX4.30TestBox init.d]# find .|grep appx ./uappxd-log-8431 ./appxd-8430 ---+++ 004) (Suggestion) Windows' APPXDSVC.exe supports -status argument by itself to list all APPX services. ---++++ For example on Windows: C:\Appx\appx.42a\tools>appxdsvc -status Service Name: appxd-8060 Display Name: appxd-8060 Status: running Service Name: appxd-8074 Display Name: appxd-8074 Status: running Service Name: appxd-9999 Display Name: appxd-9999 Status: running C:\Appx\appx.42a\tools> ---++++ Now on Linux: [root@APPX4.30TestBox tools]# ./appxLoginMgr -status serviceName: -status servicePath: ./ Looking for config file in -status.ini Error - can't open configuration file for service -status No such file or directory [root@APPX4.30TestBox tools]# ---+++ 005) (Suggestion) Windows' APPXDSVC supports -install as sole argument to create initial service on port 8060. ---++++ For example on Windows: C:\Appx\appx.42a\tools>appxdsvc -install appxd-8060 Configured appxd-8060 will start automatically each time you boot your system C:\Appx\appx.42a\tools> ---++++ For example on Linux: [root@APPX4.30TestBox tools]# ./appxLoginMgr -install serviceName: -install servicePath: ./ Looking for config file in -install.ini Error - can't open configuration file for service -install No such file or directory [root@APPX4.30TestBox tools]# ---+++ 006) (Suggestion) Rename .ini, .env and service names to match new names of appxLoginMgr and appxAuditLogger. Current value is appxd-NNNN where NNNN is the port number. Should be perhaps appxLoginListener-NNNN for appxLoginMgr files/services Should be perhaps appxAuditLoggerListener-NNNN for appxAuditLogger files/services ---+++ 007) (Suggestion) appxLoginMgr service creation does not initialize required environment variable APPX_KEYMAP, results in hung client on TCP logins. Probably should set APPX_KEYMAP = WINDOWS in appxLoginListener-NNNN.env file. ---+++ 008) (Error) Service definition files can get created in current working directory, which may not be where one wants them to be created. An example on Linux follows: [root@APPX4.30TestBox appx]# pwd /appx [root@APPX4.30TestBox appx]# ls [root@APPX4.30TestBox appx]# /usr/local/appx/tools/appxLoginMgr -install -port=8060 -engine=/usr/local/appx/appx 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 /usr/local/appx/appx Configuration written to: appxd-8060.ini Environment written to: appxd-8060.env Service script written to: /etc/init.d/appxd-8060 Configuration complete Registering service Starting appxd-8060: serviceName: appxd-8060 servicePath: /appx/ Looking for config file in appxd-8060.ini 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 /usr/local/appx/appx Writing process ID to /var/run/appxd-8060.pid running as process 7803 servicing 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 /usr/local/appx/appx up and running (process 7803 servicing port 8060) Installation Complete [root@APPX4.30TestBox appx]# ls appxd-8060.env appxd-8060.ini [root@APPX4.30TestBox appx]# ls /usr/local/appx/tools/appxd-8060* ls: /usr/local/appx/tools/appxd-8060*: No such file or directory [root@APPX4.30TestBox appx]# ---+++ 009) (Suggestion) Possible inconsistent requirement of the -name argument. It seems we are inconsistent in our requirements for the use of the -name argument. Examples follow where (+) works and (-) does not currently work. (-) ./appxLoginMgr -modify appxd-8060 -TCPNodelay=false (+) ./appxLoginMgr -modify -name=appxd-8060 -TCPNodelay=false (-)./appxLoginMgr -status (+)./appxLoginMgr -status -name=appxd-8060 (+) ./appxLoginMgr -stop appxd-8060 (-) ./appxLoginMgr -stop -name=appxd-8060 (+) ./appxLoginMgr -start appxd-8060 (-) ./appxLoginMgr -start -name=appxd-8060 (-) ./appxLoginMgr -remove appxd-8060 (+) ./appxLoginMgr -remove -name=appxd-8060 (-) ./appxLoginMgr -status (+) ./appxLoginMgr -status appxd-8060 (+) ./appxLoginMgr -status -name=8060 ---+++ 010) (Error) The argument -replace erroneously does not require the “-name” argument If a site has two services appxd-8060 and appxd-8061 and issues the following: ./appxLoginMgr -replace -TCPNoDelay=false The tool makes the modification to the appxd-8060.ini file. It probably should force the user to use the -name argument here. ./appxLoginMgr -replace appxd-8061 -TCPNoDelay=false Fails. ./appxLoginMgr -replace -name=appxd-8061 -TCPNoDelay=false Works. (Although one would probably want to add -port=8061 in the above example) ---+++ 011) (Informational) Just a comment on -modify behavior. -modify will maintain existing values, but will actually remove and create new .env and .ini files with the new values specified. This combination action of remove and recreation will change (remove) any existing non default comments. Would not change behavior of the service but could be a surprise to someone that had input documentation remarks (via the # symbol). ---+++ 012) (Error) Red Hat's service wrapper command. Usage: appxd-8060 {start|stop|status|reload|restart} ---++++ start works without issue ---++++ stop does seem to remove the running process; however, it produces errors. Further, it fails to remove the PID from the (/var/run/appxd-8060.pid) /etc/init.d/appxd-8060: line 39: success: command not found /etc/init.d/appxd-8060: line 39: failure: command not found /etc/init.d/appxd-8060: line 43: failure: command not found ---++++ status seems to work without issue. ---++++ reload does not appear to do anything. ---++++ restart which is a stop followed by a start, suffers from the problem of stop documented earlier. ---+++ 013) (Cosmetic) Redundant redundant redundant data data data. A minimal install produces three warning statements as documented below: [root@APPX4.30TestBox tools]# ./appxLoginMgr -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-7777.ini Environment written to: appxd-7777.env Service script written to: /etc/init.d/appxd-8060 Configuration complete Registering service Starting appxd-8060: serviceName: appxd-8060 servicePath: /usr/local/appx/tools/ Looking for config file in appxd-8060.ini 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 Writing process ID to /var/run/appxd-7777.pid running as process 12156 servicing 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 up and running (process 12156 servicing port 8060) Installation Complete [root@APPX4.30TestBox tools]# ---+++ 014) (Suggestion) Warn users not to move configuration files. We should probably warn via screen notice on service creation, and document inside the .ini and .env files that if the .ini, .env and appxLoginMgr/appxAuditLogger are move or renamed, then the /etc/init.d system startup script will fail to work. The /etc/inid.d/appxd-8060 startup script references by name and path the .ini, .env, and appxLoginMgr/appxAuditLogger files. ---++ Comments: _Read what other users have said about this page or add your own comments._ --- %COMMENT% --- -- Page added by: [[SteveFrizzell][Steve]] - 17 Jul 2007
Edit
|
Attach
|
Watch
|
P
rint version
|
H
istory
:
r71
|
r38
<
r37
<
r36
<
r35
|
B
acklinks
|
V
iew topic
|
Raw edit
|
More topic actions...
Topic revision: r36 - 2008-06-18
-
JoeOrtagus
Home
Site map
Main web
MedicaidBilling web
Sandbox web
TWiki web
Main Web
Users
Groups
Index
Search
Changes
Notifications
RSS Feed
Statistics
Preferences
P
View
Raw View
Print version
Find backlinks
History
More topic actions
Edit
Raw edit
Attach file or image
Edit topic preference settings
Set new parent
More topic actions
Account
Log In
Edit
Attach
Copyright © 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