Client Server
The Client Server (or CS) model accomplishes 2 things:
- It integrates Linux with Windows (phase one).
- 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 Windows 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 | Windows |
| Windows | Linux |
| Windows | MAC| |
| MAC | MAC |
| MAC | Windows |
| MAC | Linux |
Components
| BRClient.exe | Client - Runs on a workstation |
| BRListener.conf | Listener configuration file (place on server in Windows dir or /etc ) |
| BRServer.exe | Windows BR Server Program (location specified in conf file) |
| BRserver | Linux or MAC BR Server Program |
| Install.exe | BRListener.exe Installer for Windows Server |
| BRListener.exe | Server side Connection Agent and Server side Connection Agent |
Installation Instructions
WINDOWS-
First modify the BRListener.Conf file and copy it into your Windows directory on your Windows 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 6 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- This executable refers to BR itself. You can initiate your application via 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.
LINUX- (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 ]
[ 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 MAC, 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.
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 Linux login script is used to start BR, 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 Linux 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 Linux | is performed on the client. | |
| -@ | Client Shell Call | If Linux - 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. | |
| Linux frames the command | ||
| with NOHUP and &. | ||
| -r (restore) | Windows always performs shell | Linux forwards standard |
| calls in a separate window. | out and stdin data to and | |
| Linux 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 Linux 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 Linux server only | without pausing. | |
| -m | Minimized under Windows | A separate application |
| -Ignored by Linux | 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 MAC / 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 / SYNC
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
- 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.
- 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.
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.
BRListener uses PORT 8555 by default. We recommend that you use a different port of your own choosing for security reasons.
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 the brserver port.
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 (or your specified port) to your server.
Many Routers provide not only forwarding, but also firewall capabilities. Make sure that your router has been configured to allow inbound traffic over port 8555 (or your specified port).
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.