Line: 1 to 1 | ||||||||
---|---|---|---|---|---|---|---|---|
Added: | ||||||||
> > |
APPX Login Manager For Unix/LinuxThis page describes how to install the APPX Login Manager command and how to use it to install, configure, and manage APPX Login Services on Unix/Linux systems. <script type="text/javascript" src="http://wiki.appx.com/wiki/pub/TWiki/TinyMCEPlugin/tinymce/jscripts/tiny_mce/themes/advanced/langs/en.js"></script><script type="text/javascript" src="http://wiki.appx.com/wiki/pub/TWiki/TinyMCEPlugin/tinymce/jscripts/tiny_mce/plugins/twikibuttons/langs/en.js"></script><script type="text/javascript" src="http://wiki.appx.com/wiki/pub/TWiki/TinyMCEPlugin/tinymce/jscripts/tiny_mce/plugins/twikiimage/langs/en.js"></script>
Installing the APPX Login 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. 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 "/usr/local/appx", the full pathname of the appxLoginMgr command will be "/usr/local/appx/services/appxLoginMgr". The appxLoginMgr command must run with the permissions of the root user because it will be spawning appx processes running as each logged in 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.You can check the permissions of the appxLoginMgr command by running the following command: The recommended permissions should be as follows:ls -l appxLoginMgr -rwsrwxr-x 1 root root 636843 Jul 11 07:31 appxLoginMgr Creating and Configuring an APPX Connection ServiceOn 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 ServiceBefore 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:
The Name of the ServiceEach 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, appxd-8060.TCP/IP Port NumberWhen 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 ServiceTwo 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 daemon configuration files (ini and env) 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 - Text EditorA text editor can be used to directly edit the APPX Login Manager daemon 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 an APPX Login Manager daemon is with Medhod 1 above.Managing an APPX Login Manager DaemonTwo methods are available for managing an existing instance of the APPX Connection Service.Method 1 - appxLoginMgr commandThe 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 ServicesYour 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. Red Hat uses the command line tool service .[root@tubes tools]# service appxd-8060 status up and running (process 13893 servicing port 8060) Usage (appxLoginMgr)-Umask=FILECREATIONMASK 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. -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} 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 attemps 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.required - APPX clients must request an SSL connection disabled - APPX clients may only request a plain text connection -TrustedCAFile=CAFILENAMEoptional - APPX clients may request either an SSL connection or a plain text connection 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 idenfies the pathname of server's private key file (unlocks the <nop>ServerCertificateFile).-RequireSSL={true, false} This option is not needed and has not been implemented.-RequireSSLClientCertificates={true, false} This option is not needed and has not been implemented.-ServerPrivateKeyPassphrase=PASSPHRASE This option is not needed and has not been implemented. Configuration - Environment VariablesVARIABLE=VALUEYou 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 ManagementappxLoginMgr [-start | -stop | -restart | -status] {SERVICENAME | -serviceName=SERVICENAME}MANAGEMENT OPTIONS -start | < blank >-stopStart an instance of the Login Manager service using the configuration information in the SERVICENAME.ini and the SERVICENAME.env files. Stop the instance of the Login Manager service that was started with the SERVICENAME.ini file.-restart Restart (stop and then start) the instance of the Login Manager that was started with the SERVICENAME.ini file.-status Report the status of the instance of the Login 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: appxLoginMgr -install -port=8060 appxLoginMgr -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: appxLoginMgr -status appx8060 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=WindowsWarning - 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 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 appxLoginMgr 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 appxLoginMgr command is run to create the service. Therefore, before you run the appxLoginMgr 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 appxLoginMgr 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 appxLoginMgr 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 appxLoginMgr command is run to create the service. Therefore, before you run the appxLoginMgr 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 appxLoginMgr 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 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.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 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.*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 Red Hat service command.
Examples:How to create private/public-keys without passphrase for serverExample of appxLoginMgr parameter to identify private key:ServerPrivateKeyFile =/usr/local/appx/tools/tubes.internal.appx.com.private.keyExample of openssl command to create private key: openssl genrsa -out tubes.internal.appx.com.private.key 1024 How to create public SSL certificate for serverExample of appxLoginMgr parameter to identify SSL certificate:ServerCertificateFile =/usr/local/appx/tools/tubes.internal.appx.com.crtExample of openssl command to create SSL certificate: openssl req -new -days 365 -key tubes.internal.appx.com.private.key -x509 -out tubes.internal.appx.com.crt Warnings:"the engine that you named has the setuid bit enabled"This warning message is displayed when you start a service and the engine specified for AppxExecutable has the setuid bit set. When launching an APPX session, the APPX Login Manager sets the real user ID and the effective user ID of the APPX session based on the value specified for the <nop>ImpersonateUser parameter. If the engine has the setuid bit set, then the effective user of the APPX session will be changed by the operating system to be the owner of the APPX engine and the APPX session will run with the permissions of that user.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 Issues:
Enhancement Suggestons:
Comments:Read what other users have said about this page or add your own comments.-- Page added by: Steve - 17 Jul 2007 |