APPX Client/Server Installation and Configuration

APPX Client/Server Installation and Configuration

Overview:

This information only applies to very old versions of APPX (pre 4.2). Consult the installation instructions for your release for more up to date information.

APPX/Client lets users run the user-interactive portion (keyboard, mouse, and monitor) of the APPX Development and Runtime Environments on local PCs as thin clients, with the bulk of applications running on an APPX/Server. APPX/Client runs under Windows 95, Windows 98, Windows NT, Windows 2000, and Windows XP, as well as several distributions of Linux.

APPX/Server resides on a central UNIX, Windows, or Linux server. It connects to APPX/Client over a TCP/IP link, which can run over the Internet. APPX/Server waits for APPX/Clients to log in to it. After authenticating Clients, it launches an APPX Application Server session to service each remote Client.

APPX Application Server processes are identical to locally invoked copies of APPX, except that the APPX/Client at the other end of the TCP/IP connection handles keyboard screen and mouse operations. Also, facility is provided to run processes on the remote Client.

In addition to APPX/Client, APPX/Server can also service APPX/Net Clients. APPX/NET allows APPX Applications running on remote platforms (Windows or Unix) to access APPX data on local platforms (including data accessible locally via APPX/RDMS back end connections).

Thus, APPX/Server can service both thin APPX/Clients and APPX/NET Client processes on remote processors. APPX/Server runs on all APPX platforms except VMS.

To install and configure APPX/Client and APPX/Server, do the following:

Install APPX/Client on Client PC
Install APPX/Server for Unix, or...
Install APPX/Server for Windows
Invoke APPX/Client from Client PC
Create Multiple APPX/Servers
Notes
Deault Keymap

Installation and Configuration

Install APPX/Client on Client PC.

Copy the appx.exe engine from an existing copy of APPX for Windows (release 3.3 or greater) to your Client PC. Make sure that the release version of APPX for Windows that you are using on your client matches the release version you are running on your UNIX or NT server.

If you don't have a copy of appx.exe readily available, you can download it:

From here for APPX Release 3.5 or

From here for APPX Release 4.x

(The Windows Client is ~1.6 meg.)

Install APPX/Server for Unix ("appxd")

Get a Product Registration for APX / GCS.

The GCS (GUI Client/Server) Product Registration is a lower level registration to your main APPX Registration. Product Registrations are editable from the APPX Main Menu via 3) System Administration, 1) System Setup, 1) System Registration. Then press ENTER to edit your Product Registrations.

To request a GCS Product Registration, send an email to Tech Support ( techsupp@appx.com).

Check for presence of APPX/Server components.

There are two components to APPX/Server: the 'appxd' daemon, and the 'start-appxd.sh' shell script. The script is used to invoke the 'appxd' daemon. Both components reside in the 'tools' directory ($APPXPATH/../tools/).

The "root" user must run 'start-appxd.sh'. It launches the appxd daemon that then runs in background, waiting for APPX/Clients to start up. When new APPX/Clients link up with appxd, they spawn new APPX/Server sessions, one per client.

**'appxd' must be owned by root, and have its 's' bit set.**

These may be accomplished by:

chown root appxd
chmod 755 appxd
chmod u+s appxd

Modify 'start-appxd.sh' to specify the correct APPXPATH.

In 'start-appxd.sh', you will find a statement ...

APPXPATH="//data"

If APPX is installed in /usr/appx, you would modify this to ...

APPXPATH="usr/appx/data"

Set your TCP/IP Socket Port to assign to the Application Server

You will find the statement ...

APPX_PORT=8060

If you are running only a single server from your system (as is usually the case), you will probably be able to leave this APPX_PORT set to 8060 (an arbitrary number). The important thing is that your Socket Ports be unique.

Optional: You may want to put a 'memo' entry into the /etc/services system file, reserving socket port #8060, or whatever port# you choose, in order to avoid possible future conflicts with socket ports used by other server applications.

Point APPX_SERVER to the desired APPX Engine.

Typically this is ...

APPX_SERVER=$APPXPATH/../appx

Make sure the APPX_SERVER appx engine actually exists at the path indicated in the last step.

Make sure the APPX_SERVER appx engine is actually an engine, and not a script that then executes an APPX engine.

Permissions on the APPX_SERVER appx engine should be 755 with the 's' bit set, and should be owned by the user 'appx'. You can do this by:

chown appx appx
chmod 755 appx
chmod u+s appx

The permissions on the directory containing the 'appx' engine should also be 755. You can do this by cd'ing to that directory and using:

chmod 755

Launch 'start-appxd.sh', as 'root' user

You must launch 'start-appxd.sh' as the root user, either from the Unix command line or through some operating system facility such as 'inittab'.

To see your presentation server(s) running in background, execute the command:

ps -ef | grep s=

ps -aux | grep s=

Install APPX/Server for Windows ("WinAppxD")

Get a Product Registration for APX / GCS

(Note: only required for releases prior to APPX 4.1.a)

To request a GCS Product Registration if you're running a release prior to APPX 4.1.a, send an email to Tech Support ( techsupp@appx.com).

Check for presence of required Windows NT Resource Kit components

Some files from the Microsoft WinNT Resource Kit are required to run the APPX/Server on Windows NT. The Resource Kit includes a utility that allows WinNT users to convert most desktop applications into a SERVICE application. This means that you can run an application behind the scenes i.e. it doesn't depend on a specific user to log on. SERVICE applications re-activate themselves after NT PCs loose power and re-boot themselves.

If you have already installed the WinNT Resource Kit, you should see three files in your server's \SRVANY directory: SRVANY.EXE, INSTSRV.EXE and SRVANY.WRI.

If the directory and/or files don't exist, install them now using the instructions provided with the Resource Kit. Create a directory in the root called "\SRVANY", then copySRVANY.EXE and INSTSRV.EXE into it. (The Resource Kit must be purchased from Microsoft. It is not obtainable on-line. If you subscribe to Microsoft's TechNet, you may already have the Resource Kit on one of those CD's. Otherwise, obtain it directly from Microsoft or a bookstore. Be sure to get the Resource Kit version that matches the version of NT that you are running.)

Be sure not to delete SRVANY.EXE as long as you want to use APPX/Server. Winappxd.exe is started by SRVANY.EXE, and if SRVANY isn't there, it can't start.

Create an NT user account to run the WinAppxD service (first-time installations)

Create the NT user account that will be used to run WinAppxD. You can name it anything you like. Place this account into the Administrators group.

Use your normal net account-creation process. This usually involves invoking NT's User Manager or User Manager for Domains.

If installing APPX on a Windows NT Workstation computer, and your LAN's logins are normally validated against a PDC, and that NT Workstation computer is a member of a domain, go to your PDC and create the account using User Manager for Domains. (Don't just create it locally on the server. Unless you have the domain user management tools from the \CLIENTS\SRVTOOLS directory on the NT Server CD-ROM installed on the NT Workstation machine, which you probably do not, you can't create a domain account from your NT Workstation).

If installing APPX on a Windows NT Server computer that you installed as NOT being part of a domain, and your LAN does not have a domain to join (possibly because this is just your test "play" system and NT has not been rolled out yet), use the User Manager application on the NT Server computer to add the user.

What to do next depends on how your organization's NT network is set up. If in doubt about NT network issues, check with your site's NT administrator to find out whether the following applies to you.

If the organization's network includes a 'Primary Domain Controller' and an NT domain, but the server you are installing APPX on is a 'member server' of the domain, NOT a Primary or Backup Domain Controller, you must perform the following extra steps:

The steps below describe how to do this on an NT Server computer. NT Workstation has a slightly different user interface, so the instructions below can't be followed "click by click" if you're installing on NT Workstation.

Note: To perform this next step you MUST be physically seated in front of your APPX Server machine, and be typing on its keyboard, using its mouse. Performing this step from a PDC or BDC if your APPX server is not a PDC or BDC, is guaranteed not to work. Performing this step from another random server or workstation on your network, rather than the APPX server, is also guaranteed not to work.

From the 'Users' menu, open the 'Select Domain' dialog.
In the 'Domain' box, type the name of the machine on which you are installing WinAppxD. (Yes, that is counter-intuitive. However, it is necessary).

The extra steps are necessary if you're running on a 'member server' or NT Workstation because User Rights must be set on a per-machine basis. If you add the rights on the PDC or BDC, they will not be in effect for any member servers or NT Workstation computers, just for the PDC and BDC. This is an NT security feature.

If you are installing APPX on a PDC or BDC, then all you have to do is go to the 'Users' menu, choose 'Select Domain', and make sure that the domain of which that machine is a PDC or BDC, is selected.

Assign WinAppxD User Rights

You are ready to add required Advanced User Rights to the WinAppxD User:

Open the User Rights dialog. Start Button, Programs, Administrative Tools, User Manager, Policies, User Rights (on NT).
Check the box labeled 'Show Advanced User Rights'
Select the NT user account you created, to run WinAppxD (Do not assign rights to this user through a Group. Rights must be assigned directly to the WinAppxD user account.)
Add to it the following advanced user rights:
- Act as part of OS
- Increase quota
- Replace a process level token
- Logon as service

Give Users Local Logon rights

While in User Administration, add the "Logon Locally" right to any NT User ID which will access APPX.

This is not normally on by default. If you do not add it, the Windows and Java GUI clients will not be able to successfully start up and interact with an APPX session.

Install the WinAppxD service (first-time installations)

From the DOS Command prompt, navigate to the \SRVANY Directory. Type:

INSTSRV WinAppxD c:\srvany\srvany.exe

Notice the second element on the command line "WinAppxD". This is the "name" of the service that you will create. Later, you will go to the SERVICE applet in the CONTROL PANEL and will access the service by this name.

If everything went well, you should see a message stating that the requested service has been added. If you do not get this message, review everything that you did so far. Make sure that the SRVANY.EXE and the INSTSRV.EXE are in the directory that you specify.

Set application path for WinAppxD service (first-time installations)

Fire up REGEDT32.EXE. This is dangerous territory. One false move and you can kill your WinNT system. Don't let it put you off though, just be careful. Don't mess with other stuff while you're in there for this particular mission.
Open up the HKEY_LOCAL_MACHINE window and double-click on the SYSTEM branch. The branch opens up and you should see the CurrentControlSet branch. Double-click on that one and the Services branch should appear. Double-click on the Services branch and a long list of branches is displayed. Careful, now you are in the snake pit.
Scroll down until you find the name of the service that you created. It should be WinAppxD if that's the name you chose earlier. Double-click on WinAppxD and leave this highlighted.

Move the cursor up to the EDIT menu bar and click on "Add Key..."
The Add Key dialog box is displayed. In the "Key Name" text box type: Parameters. You don't have to enter anything in the "Class" text box. Press OK.
Highlight the Parameters Key. Bring your cursor to the EDIT menu bar again. Click on the Add Value choice.
In the "Value Name" text box type in: Application
From the "Data Type" list box choose: REG_SZ
Press OK
The String Editor Dialog box will open up. Enter the full path to the WinAppxD Server executable plus the option for the port to listen on. In my case it is:
- c:\appx\tools\WinAppxD.exe -s=8060

Press OK and get outta there.

Close it all up and exit the REGEDIT32 program. Now you can breathe easy again. The worst is over.

Assign WinAppxD to an NT User (first-time installations)

Go to the Control Panel. Open up the SERVICE Applet, scroll to the WinAppxD line, and double click on it.
A dialog box opens up. Choose the Startup Type: Automatic. (For unattended operation: this will allow WinAppxD to be active when there is no one logged on).
Click on This Account and type in the name of the NT user account you created to run WinAppxD.
Press OK, and choose Close in the Services applet.

Install and configure APPX License Server

Repeat the Service install steps 5 - 7 again for the license server. Call the service 'AppxLicSrv' instead of WinAppxD.

If your appx.exe engine resides at C:\appx\appx.exe, then the Application value registry setting in step 5.7 will be c:\appx\appx.exe -l=c:\appx\log. (This tells APPX to store the server log in the APPX engine location.)

You can use the same NT User Account created to run WinAppxD; there's no need to create another one.

(Substitute the proper paths to your APPX executable and log file here.)

Set APPX environment variables

Using the System applet in the Control Panel, add the following variables to the environment:

APPX_SERVER=c:\appx\appx.exe
APPXPATH=c:\appx\data
APPX_KEYMAP=WINDOWS
APPX_NET_LOG=C:\WinAppxD.log
APPX_NET_LOG_MASK=0xFFFFFFFF

Be sure to set these in the global System section, so that they will be in effect for every user, not just in the "User" section.

To set an NT System environment variable, go to: Start, Settings, Control Panel, System, Environment Tab. You'll see System variables at the top of the scrolling list, User variables at the bottom.

Click on one of the existing System variables. It will display down below in the variable/value editable fields. Overtype the existing variable name with your desired variable. Fill in the desired value in the value field.

The new System variable/value should show up at the top of the System/User variables list, without deleting or changing the variable from which you cloned it.

Set desktop heap size to 512 for non-interactive processes

Follow the instructions in the Microsoft Knowledge Base article http://support.microsoft.com/support/kb/articles/Q142/6/76.asp to decrease the desktop heap size in the registry.

If this is not done, you are likely to receive USER32.DLL errors when running external programs from APPX (including winprint.exe, which is used for printing APPX output).

Reboot and enter registration data

Reboot the machine, and enter your registration 'c:\appx\appx.exe

Start a license server and run APPX

Start a License Server "c:\appx\appx -l=c:\appx\log". Then start appx "c:\appx\appx.exe" to create System Administration file and add users. Make sure you add a user whose 'System ID' matches the name of the NT user account you're using to run the License Server, so that the license server you add as a service will be able to start.

Reboot

Reboot the system again and you should be ready to run. You can test your setup by shutting down the machine properly and re-booting. WinAppxD will be active before you even log on. Try to access the WinAppxD Server now from the same or another machine by running "appx.exe -c".

If you run into problems, check out the WinAppxD FAQ. It includes answers frequently asked questions about installing and running APPX/Server on Windows NT.

The APPX_NET_LOG set up above is used to monitor APPX/Server traffic, for debugging. Once you have APPX/Server working with APPX/Client, you should either remove the APPX_NET_LOG environment variables, or set APPX_NET_LOG_MASK=0x00000000 so you can just change the mask back if you ever need to do any debugging. APPX_NET_LOG can take quite a bit of disk space over time.

See the WinAppxD FAQ , Section 6 (Troubleshooting), for more information on the use of the APPX_NET_LOG.

Invoke APPX/Client from Client PC.

The fastest way to test APPX/Client from your Windows client is to call up the MS-DOS box, then type the following at the DOS prompt (assuming for example that you've installed the engine in c:\appx) ...
- c:\appx\appx.exe -c
- You can also set this command string up into your "start button" or Program-Manager menus under all versions of Windows
Under the "appX Login Information" popup box, enter your Unix server's "User Name" and "Password".
- For "Remote Host", enter the IP address (numeric or symbolic) of the Unix host running the APPX/Server.
- (If your PC Client is already connected to a host server via tcp/ip, and you need to determine the IP address of the server, (and, for example, your server host is known as 'bertha'), then you can find your IP address by typing:
- grep bertha /etc/hosts
- For "Server Port", enter the APPX_PORT (usually 8060) defined for the server above as the "Server Port".
- If you want to remap from the default APPX Windows keymap, check the "Remap Keyboard?" box. (It is not currently possible to edit the default APPX Windows keymap.) Then, click the "Login" button.
- After a brief pause, you should either be logged into your APPX/Server, or get a popup error box describing a problem with the connection.
- If it does not work, the best thing to do is to try to run appx directly from the server (by logging into the server's console or telnet'ing into it, as the same user you're trying to login as, via Client/Server), and verifying that you do indeed get the APPX Startup screen.

Create Multiple APPX/Servers.

Once you have your base APPX/Server working, we recommend setting up multiple APPX/Servers. It's possible (though rare) for IP ports to get hung at the Network or O/S level. If you have fallback Server ports standing by (ex: 8061, 8062, ...), you can avoid having to reboot your Server to clear the port.

To set up additional APPX/Servers, follow the "Install APPX/Server" instructions above, substituting other port numbers for 8060. For Windows APPX/Servers, you don't necessarily need to have different copies of WinAppxD.exe, but when you add the services, you must use different names, i.e.:

INSTSRV WinAppxD1 c:\srvany\srvany.exe
INSTSRV WinAppxD2 c:\srvany\srvany.exe

When you enter the information in the registry, they will all point to the same .EXE file, but have different port numbers on the command line.

There can be advantages to using renamed copies of WinAppxD. Different executable names allow you to differentiate APPX/Servers within your Windows Task Manager.

Services can also start Batch files, which can be used to start WinAppxD with different ports and environment variables. You can use this to set up a port with APPX_NET_LOG debugging, or to run different APPX versions on different APPX/Server Ports. Note that you will have a CMD.EXE sitting in your NT task list until the task it started completes.

A sample batch file to run an APPX/Server might be:

SET APPX_SERVER=C:\appx\appx413\appx.exe
SET APPXPATH=C:\appx\appx413\data
SET APPX_KEYMAP=windows
SET APPX_NET_LOG=C:\appx\appx413\net.log
SET APPX_NET_LOG_MASK=0xFFFFFFFF
C:\appx\appx413\tools\winappxd.exe -s=8413

This batch file would run an APPX instance in the C:\appx\appx413 directory tree, with APPX_NET_LOGing turned on. The directory and name of a batch file such this would be entered into the registry, in place of the "c:\appx\tools\WinAppxD.exe -s=8060" described in "7. Set application path for WinAppxD service" above.

If you use a firewall, remember to punch holes in it for the ports you turn on.

NOTES:

The presence of Unix APPX/Server running in background may be detected via the command ...

ps -ef | grep appxd

... which will give output similar to the following ...

root 27838 Jul 18 0:00 /usr/appx/data/../tools/appxd -s-8060

The presence of Unix APPX/Server sessions (one per APPX/Client) may be detected via the command ...

ps -ef | grep f-

... which will give, for each APPX/Server session, output similar to ...

pat 13330 17529 0 23:52:50 ? 0:00 appx -f-4

Early versions of APPX/Client do not remember the prior settings for UserID, Password, RemoteHost IP Address, or ServerPort values for the prior session of APPX/Client, when logging in to subsequent sessions of APPX/Server. "Save as Default" will be implemented in future APPX/Client releases.

Running "appx -c /login" will force the login dialog box under Windows 95 and NT, allowing override of the defaults pulled from the Windows installation files.

Your choice of Windows Control-Panel Colors can significantly affect the "looks" of APPX/Client. If for example you specify (in Windows) that foreground text is 'White', then editable fields in APPX will display as White on White, and be unreadable. We expect enhancements to color-selection in future releases of APPX/Client.

The Default Keymap shipped with APPX/Client follows. We expect to be able to edit the default keymap in a future release.

esc=GO

f1=help

f2=scan

f3=select

f4=prev image

f5=next record

f6=pan

f7=scroll

f8=end

f9-12=Add/Delete/Inquire/Change

PageUp=Previous Screen

PageDown=Next Screen

`=Option

0-9=Numeric Digits

HOME=Home. Not currently mapped.

END=Vertical Tab. Not currently mapped.

Comments:

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

Topic revision: r8 - 2016-04-05 - JeanNeron