Client Server

From BR Wiki
Jump to navigation Jump to search

The Client Server (or CS) model accomplishes 2 things:

  1. It integrates Unix with Windows (phase one).
  2. It extends the server environment to the client with respect to printing and file transfers (phase two).

Please note that REMOTE PRINTING is a logical requirement of using CS with NT/W2K/XP servers because these operating systems were not designed to support CS server printing. When a login is authenticated on a Windows server, the user is granted access to their own defined printers only if they are also logged into the server's desktop. This means REMOTE PRINTING (printing through the user's desktop) is a practical prerequisite of using the CS model with Microsoft servers. (See REMOTE PRINTING details below.)

Supported Platforms

Client Server
Windows ME --
Windows NT Windows NT
Windows 2000 Windows 2000
Windows XP+ Windows 7+
Vista Vista
-- Linux
-- SCO Openserver
MAC MAC

Components

BRClient.exe Client - Runs on a workstation
BRListener.conf Listener configuration file (place on server in Windows dir or /etc )
BRServer.exe NT BR Server Program (location specified in conf file)
BRListener.exe Server Connection Agent for NT (place in Windows\System32)
Install.exe BRListener.exe Installer for NT Server (can be found at the bottom of [br_version]_WinSvr.zip on the web site download section ( http://www.brulescorp.com/brules/download.html ))
BRServer.exe SCO BR Server
BRListener.exe Server side Connection Agent and Server side Connection Agent

InstallShield Installation Instructions

Before Running Setup Please Read:

TIP: You must be logged in as Administrator in order to run Setup.

If you have a BR Service running
1.) Stop the BR Service on the machine where you intend to install. If your previous installation was done using InstallShield, use "stop BR service" from the Programs/BR Service icon list.
2.) You can also stop the BR Service by going to start, run, and typing "install /release".
3.) If your previous installation was done using InstallShield, you can remove it by using the Add/Remove Programs feature in the Control Panel. In this case, your BRConfig.sys and license file (brserial.dat) will not be removed. This is to make them available for subsequent use.
4.) When you run install, installation will modify your BRListener.conf file if your target directory is different from the one previously specified.

How to use the Program Menu.

After running the installation, you can use the Program Menu to start, stop and test BR Server. In order to test the server, the client application is also included in this package. To test client and server, simply click the "test client-server" icon in start/programs/BR Server. This will start the BR Client.

Release Notes

After the Setup is finished, please read the Release Notes, which are accessible from Programs/BR Server menu.

Client-Server Notes

These notes are also available from Programs Menu. You will find useful information on how to configure, start, and use the service, or how to manually install this service.


Manual Installation Instructions

WINDOWS-

First modify the BRListener.Conf file and copy it into your Windows directory on your NT server. Change the logfile, the executable and the startdir as necessary. Startdir is used on the server. It specifies the BRserver initial working directory. This is where it will look for BRConfig.sys. However a different configuration file name and path can be specified in the session statement. This may be desirable when you are using both conventional and CS models together, with different screen specifications for each.

The brlistener.conf file has three statements:

logfile= specifies the location and name of a trace file ( do not use quotes nor spaces in this path) loglevel= leave at 10 for now - may be significant later
port= port number to use (default is 8555)

The brlistener.conf session statement format is:

LABEL=BR       Arbitrary statement label name - must be referenced in client startup command
STARTDIR=      Starting server directory ( do not use quotes nor spaces in this path)
STDERR=        Filename to contain error reports.
EXECUTABLE=    Pathname of BRserver executable.  Note- You can now initiate an application from a BRCONFIG.SYS EXECUTE statement.
CAPTION=       The client login prompt window caption.
CONFIG=        Pathname to BRConfig.sys file - optional - defaults to server startdir
ANONYMOUS=     username@password - optional (see below)
MULTISESSION   This keyword tells the brlistener to allow multiple sessions to operate with a single login. If your application doesn't support multiple sessions, omit this keyword.
Example

[ LABEL=BR STARTDIR=C:\Myapp EXECUTABLE=C:\Myapp\BR\brserver CONFIG=C:\Myapp\brconfig.svr ]

Session Statement Notes:

If the client fails to connect with the server, for now, remove all but one label statement.

Any names containing blanks must be enclosed in quotations.

The WSID may be set in the CONFIG file according to username. See BRConfig.sys for more information.

Activating the Server

After the brlistener.conf file is in place on the server, install (activate) the brlistener.exe NT service on the server. This can be done by placing BRlistener.exe in the Windows\System32 directory and then logging in as administrator and running Install.exe. Once the listener is installed as a service, it will automatically be invoked each time the server is rebooted.

The brlistener.conf file is processed only at the time the listener is started. So if it needs to be changed, you must uninstall (see remove below) and reinstall the listener to activate the revised conf file.

At this point if installation is successful NT Diagnostics/services will have an entry for BR_Listener. If the logfile has been set up appropriately it should now be created and have a few messages in it. Rebooting is NOT needed in order to use it.

If all has worked so far you should be able to launch the client. To launch the client run
      BRclient computer BR

Where 'computer' is an IP address or IP name and BR is the labelname in brlistener.conf. You can get your server's IP number by going to a DOS shell and running 'ipconfig'.

TO REMOVE the listener from your system, the install program may be used by typing install /release.

Security Issues:

If ANONYMOUS= is specified, all users accessing the process will be logged in under username on the server. In this case, the user is not requested to provide his or her name and password, and it is not possible to specify a particular WSID for the user. USE THIS FEATURE WITH CAUTION. It is left up to the application to authenticate access. USERNAME SHOULD HAVE RESTRICTED OS ACCESS. Remember, it is possible to access any pathname under BR by preceding the reference with a colon.

You may wish to remap command characters such as ctrl-A to a null value. If you wish to make interrupts possible by only your support staff, you can map hex CO, or any other BR line draw character, to 01 (ctrl-A). Hex C0 is generated by the digit 1 only when in line draw mode which is toggled by ctrl-\. (e.g. keyboard 01 41, keyboard C0 01 - accessed by ctrl-\ 1 ctrl-\)

Generally, BRserver inherits the security privileges of BRlistener. They are then restricted according to the permissions of the person logging in (or the "anonymous=" username).

Note regarding 2003 Server:

When using client-server BR with a Windows 2003 Server, users need to have the permission “Allow log on locally”. By default, Windows 2003 Server only grants this permission to administrators. This setting can be enabled using the Domain Controller Security Policy administration utility. This can be found though:

 Start -> Administrative Tools -> Domain Controller Security Policy

After starting the utility, in the tree, go to

 Security Settings -> Local Policies -> User Rights Assignment

This will bring up a list of policies in the window to the right and one of them will be:

 Allow log on locally

To add/edit users that have this permission double click on it.


UNIX- (first read the Windows install instructions)

Revise the brlistener.conf file appropriately. See the Windows install section for brlistener.conf specifications.

Examples-

  [ LABEL=BRX  STARTDIR=/u/myapp  EXECUTABLE=/u/myapp/br/brserver CONFIG=/u/myapp/brconfig.svr ]
00000 or -
  [ LABEL=BRX  STARTDIR=/u/myapp  EXECUTABLE=/u/myapp/br/brserver.script CONFIG=/u/myapp/brconfig.svr ]
Where brserver.script contains
      TERM=ansi;            # this is not needed for BR to work
      export TERM;
      /u/myapp/br/brserver run menu $*

Note- The trailing $* is required.

Copy or link brlistener.conf to the /etc directory.

Place brserver in the directory where it will reside.

As superuser, execute brlistener. It will configure itself as a daemon. If the logfile has been set up appropriately it should now be created and have a few messages in it.

At this point you should be able to launch the client (either Windows or SCO, or both)

BRclient computer BR ( 8555 )

Where computer is an IP address or IP name and BR is the labelname in brlistener.conf.

To remove the listener from your system simply kill the process (-9 not needed). This may be handy for restarting the listener - especially since its configuration file is only read when it starts.

You will need to put the startup command into either inittab or rc2.d in order to automatically start the brlistener upon bootup.

LINUX-

You should install the listener and the server the same as you would for Unix.

A script has been written (brlist) to make the listener into a service on Linux. This makes it easy to initiate the listener in a way that it automatically starts at bootup and it is easily managed thereafter. The name of the script is "brlist". This script is self installing. First (as superuser) copy the script into a temporary directory and make it executable. Next place a link to brlistener in /usr/sbin (or copy brlistener to /usr/sbin) and make it executable. Then type "./brlist install". This will copy the script to where it will be needed and it will establish bootup linkage to itself.

Thereafter the listener can be (re)started or stopped as follows
*      brlist start
*      brlist stop
*      brlist restart
Linux Installation Checklist

This installation assumes that both terminals and clients will access the application. Filenames are shown in uppercase. However they will actually be lowercase.

1.) Setup the normal BR terminal based application.
2.) In the BR program directory place BRLISTENER, BRLISTENER.CONF, BRSERVER, BRLIST and BRCONFIG.SVR.
3.) BRCONFIG.SVR contains OPTION 30, a SCREEN statement and GRAPHIC_LINEDRAW SUNKEN, in addition to including the regular BRCONFIG.SYS.
4.) BRLISTENER.CONF STARTUP= this directory EXECUTE=/path/BRSERVER (or a script) CONFIG=BRCONFIG.SVR.
5.) Link BRLISTENER.CONF to /etc.
6.) Link BRLISTENER to /usr/sbin.
7.) Make sure permissions are correct on all of the above files.
8.) ./BRLIST install
9.) If a script is used, be sure there are NO echo or other screen output statements, the PATH and other environment variables are set the way they would normally be in PROFILE processing, and that the BRSERVER invocation ends with $*

Also see #Installing Lexi

SHELL CALL (SYSTEM command) PARAMETERS

Concerning Unix shell calls the following flag combinations are prevented-
-W and -C
-R and -C
-W and -R
In other words Without Shell, Restore Screen, and Continue are mutually exclusive options. If more than one is specified at a time error 2222 is generated.

The ability to perform the System command on the server will be able to be disabled for anonymous sessions. Clients will also be able to prohibit all client file operations.

FLAG RESULT OMITTED
-s Server Shell Call If Windows - shell call
-Default for Unix is performed on the client.
-@ Client Shell Call If Unix - shell call is
-Default for Windows performed on the server.
(search path not implemented on client)

Important Note- Ctrl+] ALWAYS performs a DOS shell call on the client.
PRIMARY

FLAG RESULT OMITTED
-c Windows launches task and Wait until process is
resumes BR operation done up to a maximum of
(like it did before). SHELL LIMIT seconds.
Unix frames the command
with NOHUP and &.
-r (restore) Windows always performs shell Unix forwards standard
calls in a separate window. out and stdin data to and
Unix ignores shell standard from the client window.
out data.
-w Without Shell - Program -Timeout / Ctrl-A does
called directly. MUST be a not kill process..
program (not script) can leave orphans.
-Search Path is used ON
SERVER only (if no slashes)
-Does not open a DOS window
-Does not use Bourne shell -
enables unfiltered return values
-Timeout / Ctrl-A kills process.

Note- Currently -w is ignored in Unix standard models.

FLAG RESULT OMITTED
blank Application standard output see above
is forwarded to the client.
However the Bourne shell is
utilized to initiate the process.
Can be an executable script.


SECONDARY

FLAG RESULT OMITTED
-p Page Standard Output Output goes to screen
-Applies to Unix server only without pausing.
-m Minimized under Windows A separate application
-Ignored by Unix window is created.
-M Minimized and doesn't appear on the task bar.
-t9999 Wait up to specified seconds. Wait up to SHELL LIMIT
(client server only) seconds.

BRConfig.Sys Additions

SHELL LIMIT 9999

Sets default timeout - maximum seconds to wait for a child process. If not specified, this value is set to 240 seconds. Minus one ( -1 ) indicates never timeout unless -t is specified in the System command.

Timeout flag on shell calls - only works on client server model.

Use the config statement "SHELL LIMIT -1" to force unlimited waiting. See BR_CS.Txt for further details.

SHELL DEFAULT CLIENT / SERVER

Sets default location of shell operation and WBPLATFORM$ to WINDOWS / LINUX.

The WBPLATFORM$ system function now returns WINDOWS when running unix / aix / linux client server when the config statement SHELL DEFAULT CLIENT is present. This allows programs that test for the Windows platform using WBPLATFORM$ to run in Windows mode in the client server environment. In this case, since shell calls occur on the client, and printing occurs on the client, the program's environment is that of the client's, even though the application and all file IO is actually running on the server.

Client_Current_Dir now supports / @S

Remote Printing

Remote Printing is used in the Client Server model of Business Rules!

Valid Business Rules printer names are:

  • LPT1: ( port name )
  • PRN://10 original BR printer designation - denoting LPT1:
  • PRN:/ printer number or name

Normally legacy programs redirect PRN:/ printer names to one of the following (via SUBSTITUTE configuration statements):

  • WIN:/ case sensitive printer name substring (partial name)
  • PREVIEW:/ name substring
  • DIRECT:/ name substring

In Client Server mode printing normally occurs on the CLIENT.

SPOOLCMD governs PRN:/ output, and if @ is not indicated SPOOLCMD runs and prints on the server. There is nothing, however, that prevents SPOOLCMD from forwarding spooled output to clients.

With OPTION 30- (suppress remote printing)

PRN:/ and WIN:/     print on the server
PRN:@/ and WIN:@/   print on the client

Option 31 - suppresses native windows formatting but doesn't suppress printing via Windows. OPTION 31 has been deprecated in favor of DIRECT:/

==========================================================================

 Printer                        Output Method
 Name	------------------------------------------------------------------
 PRN:/	Server:	Linux 	Linux 	   Linux	Windows		Linux
		Opt 30	Spoolcmd   both		Spoolcmd	Spoolcmd @
	------------------------------------------------------------------

 PRN:/	client	server	server	   server	client		client
	direct	lp	spoolcmd   spoolcmd	spoolcmd	spoolcmd


                    PRN:@/, WIN:/, WIN:@/ or PREVIEW:/ 

 Opt 31	client	client	client	   client	client		client
        direct mode ---------------------------------------------------->

 WIN:/	client	server	client	   server	client		client
        native windows printing ----------------------------------------->

 PREVIEW:/
  -or-
 WIN:@/	client	client	client	   client	client		client
        native windows printing ----------------------------------------->

==========================================================================


Notes

OPTION 30 is not allowed on Windows servers.

SPOOLCMD always runs on the server unless it specifies a leading @.
e.g. SPOOLCMD @ print.bat [SPOOLFILE] runs print.bat on the client.

Ctrl-P only works at a LINPUT statement or at a command prompt.

Client side reports are always created in a spool file on the client. This includes both WIN:/ and 'SPOOLCMD @' reports.

Two SPOOLPATH statements are allowed, one for the server and one for the client. The client SPOOLPATH should have '@' right after the SPOOLPATH keyword (e.g. SPOOLPATH @ ...) to designate where on the client spool files should be placed.

The config statement
SPOOLCMD  @  print.bat [SPOOLFILE]

Causes print.bat to be issued ON THE CLIENT in the client current directory.


Direct Printing

DIRECT:/ can be used in lieu of PRN:/ to ignore SPOOLCMD. DIRECT:/ is synonymous with PRN:/ except that SPOOLCMD doesn't apply to DIRECT. ( DIRECT:/ is equivalent to specifying WIN:/ with OPTION 31 on. )

Now Parametrized Printer Substitution statements are now supported along with several other NWP enhancements, including shading, boxing and pictures.

Printer_List()

Printer_List() is a system function that loads an array with local printer definitions.

An example of its use:

10 DIM A$(1)*1000
20 Printer_List(A$)
30 PRINT MAT A$

This will print a list of printer names with each followed by their respective @port-name.

The array A$ will be redimensioned by the system to the correct number of elements, but you must first dimension the length of the elements as shown in the example. Microsoft OneNote tends to include a very lengthy printer definition.


Other Client Server Operations

Copy Files

See Copy#Client Server.

Miscellaneous

  • Version 4.1 will be provided in client-server form for SCO, Linux, AIX, MAC and NT/Win2K/XP servers. BR will also be available in the combined (traditional standard) 4.0 format for Windows platforms only, and in the 4.1 standard model on all of the above platforms.
  • The client-server keepalive handshake timeout was extended by a factor of ten. This may reduce disconnects.
  • If the client fails to connect with the server, for now, remove all but one label statement.
  • Any names containing blanks must be enclosed in quotations.
  • The WSID may be set in the CONFIG file according to username. See BRConfig.Sys for more information.
  • BR's method for maintaining a keepalive connection was changed to not use UDP. So we're back to using only one type of IP protocol- We use TCP/IP only (not UDP).

Client Server Extensions

The Edit command now works with client server.

Client Exists() is now supported.

Client Server Reconnect Configuration Statement

This Client Server Reconnect Configuration Statement can be used in versions 4.3 and higher.

CLIENT_SERVER RECONNECT_AFTER=20   RECONNECT_TIME=300

The client will attempt to reconnect to the server after RECONNECT_AFTER seconds (default is 20 seconds).

RECONNECT_TIME= specifies the maximum time to be spent attempting to reconnect (default is 120 seconds) before aborting the session.

When a client is attempting to reconnect, it displays the session number it is using. The normal client login window will contain a check box that facilitates the entry of a reconnection session number. This allows reconnection from another workstation.

Troubleshooting

Sometimes client server will disconnect when executing a particularly long/slow command. In these situations, setting this command to higher values may help. Setting both values to 999 seems to work in most cases.

Caution should be used when setting this value as the workstation will appear to "Lock up" while it is waiting, and if the server actually fails, the client will wait until the time limit has been reached.


Client Server Firewall Concepts

Client Server runs on a File Server and uses TCP communications to connect with it's clients.

Typically, BRListener uses PORT 8555

Remember that the Allow logon locally Policy will need to be enabled,particularly if running on a domain controller.

In addition an Inbound policy for C:\Windows\system32\brlistener.exe should be set for port 8555.


Client Server Router Concepts

In order to use Client Server over the internet, you will need to configure your router.

While you can assign a dedicated IP address to Client Server, you may simply elect to use [NAT] and [Forwarding] or Port Forwarding to forward TCP Port 8555 to your server.

Many Routers provide now only forwarding, but also firewall capabilities. Make sure that your router has been configured to allow inbound traffic over port 8555.

CLIENT_CURRENT_DIR EXTENSION

The third parameter of the DRIVE statement applies to client-server operations. It will still be ignored for standard model operations. The third parameter, if it begins with \\ or X: ( or any mapped drive letter followed by colon) will indicate the OS full path (relative paths not allowed) to the initial client directory for the drive referenced by that drive statement. In effect this provides a client fullpath for each drive statement. Essentially, the third parameter specifies for the client what the second parameter specifies for the server.

If this parameter is not specified or does not begin with \\ or X:, then the client current directory will still be the client startup directory.

CLIENT_CURRENT_DIR supports the following parameters:

  • Full path – specifies use this path for all @: ( single colon ) file references.
  • SYNC – Treat each BR Drive individually and when you CD on the server perform the same CD on the client for that respective drive.
  • OFF – Use the client startup directory for all @: references.

The default mode is OFF.