Latest revision as of 00:14, 20 December 2012

TMG-CPRS client, like the original CPRS client, is designed to run in a Windows environment. The Astronaut client package, then, is best installed on a Windows-based computer (or in a virtual machine running a Windows OS). The clients are meant to connect to a VistA server through a networking paradigm.

Make sure you have a VistA server installed separately (on a physical server or in a virtual machine) to which the CPRS (and other) clients can connect.

Astronaut clients can work with either the Astronaut WorldVistA server or the Astronaut OpenVistA server. (The only exception is the OpenVista-CIS Stub, which starts the OpenVista-CIS client for use with the Astronaut OpenVistA server only.)

Installation

• Download the Astronaut CPRS client onto your Windows machine and install it. During installation, enter the IP address (or hostname URL) and port (9260 by default) of the server you installed in the preceding steps.
• The SSH tunneling utility PuTTY is installed with the CPRS client. It will start automatically on the first run. Do not close PuTTY; merely minimize it (to the desktop taskbar).
• Start the CPRS client:

Windows menu -> All Programs -> Astronaut -> TMG-CPRS

• Use the default login intially:

Access Code: sys.admin
Verify Code: vista!123

You can watch a YouTube video of TMG-CPRS here.

When done with your CPRS session, you can close the PuTTY SSH tunnel. Subsequently, however, you must restart the PuTTY SSH tunnel (and then minimize it) prior to making a new CPRS (or other) connection:

Windows menu -> All Programs -> Astronaut -> Astronaut SSH

You can then restart CPRS again:

Windows menu -> All Programs -> Astronaut -> TMG-CPRS

Changing Astronaut client settings

There are several settings in the Astronaut Client package that can be changed.

Changing environment variables

The Astronaut Client installer sets several Windows environment variables. These are used by the PuTTY SSH client, for example, to establish a secure SSH tunnel to the server. These environment variables must be changed from time to time, in case your network or other installation parameters change.

To access the environment variables, follow these steps.

Windows 7

See this tutorial for step-by-step instructions on editing the environment variables in Windows 7. In short,

Start Menu -> Control Panel -> Settings -> Advanced system settings -> Advanced -> Environment variables

There is also an Astronaut utility that brings up the environment variables:

Start Menu -> Programs -> Astronaut -> Sessions -> Client Variables -> Environment Variables

A list of the environment variables is displayed, each of which can be changed. For example, if the IP address of the VistA server has changed, you can change the ASTRO_SSH_HOST environment variable that the PuTTY SSH client uses to connect to it. Example:

-> ASTRO_SSH_HOST -> Edit -> Variable Value: 192.168.56.101

Note: in this example I am changing the IP address to that of an Astronaut VistA server which I installed within a Virtualbox virtual machine on my computer. (I also have a standalone VistA server on my network, so I change this variable frequently, depending on the IP address or URL of the VistA server I am using at the time.) Obviously, use the IP address (which is displayed at the conclusion of the Astronaut VistA server installation process) or URL of your own server installation.

Securing your installation

Securing the SSH conection

The PuTTY SSH connection is the entry point to your server. You ought to make this connection secure. Read OpenSSH security for more suggestions.

• Change the %ASTRO_SSH_CLIENT_PASS% (either the environment variable or explicitly in the Astronaut SSH shortcuts) to something other than not#1sostrong. This must then also be changed at the VistA server.

• You can also change the %ASTRO_SSH_clientID% and %ASTRO_PORT% for extra security, but this is an exercise beyond this guide.

Changing the SSH password on the server

• See Changing the Astronaut SSH password for a quick way to secure the SSH connection (by changing the default password).

Use an SSH keypair instead of password authentication

Password authentication (which is the default with the Astronaut platform) is not a preferred method of routine SSH connection, as it leaves the SSH server exposed to brute force password cracking attempts.

The preferred method is to generate a public/private authentication key pair and store the keys on the server and client.

• Read this tutorial on creating and using a keypair between PuTTY and OpenSSH.

• Download puttygen.exe and pscp.exe from this page into a newly created folder: C:\Users\user\Putty.

(Note: If I am using a Windows 98 virtual machine, I use C:\My Documents\ instead of C:\Users\user\.)

• Run puttygen.exe (either by creating a shortcut to it or by running it from a Command/MS-DOS prompt).

• Create an RSA 2048-bit key pair:

Puttygen.exe -> SSH-2 RSA (ticked) -> Number of bits in a generated key: 2048 -> Generate ->

-> Save public key -> C:\Users\user\Putty\id_rsa.pub

-> Save private key -> C:\Users\user\Putty\id_rsa.ppk (do not use a passphrase)

• To be used by OpenSSH, the id_rsa.pub key must be edited.

• Delete the first two lines (with the BEGIN and Comment: in them) and the last line.
• Join the remaining lines into a single line.
• Place ssh-rsa at the beginning.

The original text, such as

---- BEGIN SSH2 PUBLIC KEY ----
Comment: "rsa-key-20100302"
AAAAB3NzaC1yc2EAAAABJQAAAQEAjdp567qxsGkhELlMQup2mXHdsveCWq/maU6k
unPpbkwEuhkasuOrhkAWgv5v3d8S857zdHcfnXWi2FkEaJuFxqpJ2IkFuvqRdqYD
ZCcASj2S0LoXdWpC4uon6VH8oBT31r+wkDfmI2a+K74jgXjtm1BWWxwOpKaWQHi9
YItbY/06renRex34n3ejO20JRqD/BxnFU7ND41Szo3ZMKoa0yzhevU2ntt74BCvC
bYFHdSoRbi3AH8qGInzFfhXPdrG8qA382ZKEh5Bmy8Qxb9Uen/+jjP51YxN/ykee
RwSrdSCZekB6jN6uuTLNDEXJSJizqlPU8tROqf3pYv1kxzD9bw==
---- END SSH2 PUBLIC KEY ----

should then become

ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAQEAjdp567qxsGkhELlMQup2mXHdsveCWq/maU6kunPpbkwEuhkasuOrhkAWgv5v3d8S857zdHcfnXWi2FkEaJuFxqpJ2IkFuvqRdqYDZCcASj2S0LoXdWpC4uon6VH8oBT31r+wkDfmI2a+K74jgXjtm1BWWxwOpKaWQHi9YItbY/06renRex34n3ejO20JRqD/BxnFU7ND41Szo3ZMKoa0yzhevU2ntt74BCvCbYFHdSoRbi3AH8qGInzFfhXPdrG8qA382ZKEh5Bmy8Qxb9Uen/+jjP51YxN/ykeeRwSrdSCZekB6jN6uuTLNDEXJSJizqlPU8tROqf3pYv1kxzD9bw==

• The (edited) public key id_rsa.pub must then be copied to the VistA server. I do this by using the pscp.exe utility (which can be run either by creating a shortcut to it or by running it from a Command/MS-DOS prompt). I use the command:

"C:\Users\user\Putty\pscp.exe" -P 22 "C:\Users\user\Putty\id_rsa.pub" serveruser@remoteserver.computer.xyz:id_rsa.pub

This command uses SSH port 22 to send the id_rsa.pub key (created and edited on the client) to the remote server and naming it id_rsa.pub there. It will be sent to the /home/serveruser/ folder on the server.

• Logon to the Ubuntu Linux server (as serveruser). Move the id_rsa.pub key that was copied from the client to the ~/.ssh folder.

 mv id_rsa.pub ~/.ssh

• On the Ubuntu Linux server make sure the directory /home/serveruser/.ssh exists and that there is a file authorized_keys (with write privileges) in that folder (where serveruser is the administrative user of the Ubuntu Linux server). If not, create such a file while logged into the server as serveruser (the touch command creates an empty file):

mkdir ~/.ssh
cd ~/.ssh
touch authorized_keys

Then concatenate the id_rsa.pub key you have copied to the ~/.ssh folder. (Make sure the owner of id_rsa.pub, after copying, is serveruser.):

cd ~/.ssh
sudo chown serveruser id_rsa.pub
sudo cat authorized_keys id_rsa.pub >> authorized_keys
sudo chmod 700 authorized_keys

• Troubleshooting: Occasionally the permissions will not be right. Change the permissions during file manipulation and then change them back:

sudo chmod 777 authorized_keys
sudo chmod 777 id_rsa.pub
sudo cat authorized_keys id_rsa.pub >> authorized_keys
sudo chmod 700 authorized_keys

• Make sure the OpenSSH server knows to look for the key file. On the VistA server, edit the OpenSSH Configuration file:

sudo nano /etc/ssh/sshd_config

• Uncomment the line (i.e. remove the # at the beginning of the line):

#AuthorizedKeysFile %h/.ssh/authorized_keys

• Remove the ability to login to the OpenSSH server using a password:

 sudo nano /etc/ssh/sshd_config

• Change the line

#PasswordAuthentication yes

to

PasswordAuthentication no

• Restart the OpenSSH server:

sudo /etc/init.d/ssh restart

• Now you can connect securely with an SSH tunnel without requiring a password, but only if you login as serveruser.

"C:\Program Files\VistA\Putty\putty.exe" -ssh -i C:\Users\user\Putty\id_rsa.ppk -l serveruser -L 9201:127.0.0.1:9260 remoteserver.computer.xyz -P 22

• I prefer to keep the Astronaut structure, so I copy the keys to a folder for client9260. Again on the VistA server:

sudo mkdir /home/client9260
sudo mkdir /home/client9260/.ssh
sudo cp /home/serveruser/.ssh/* /home/client9260/.ssh/
sudo chown -R client9260 /home/client9260
sudo chmod 700 authorized_keys

• This time make sure the OpenSSH server knows the new location to look for the key file. On the VistA server, edit the OpenSSH Configuration file:

sudo nano /etc/ssh/sshd_config

• Change the appropriate line to:

AuthorizedKeysFile /home/client9260/.ssh/authorized_keys

and restart the OpenSSH server ( sudo /etc/init.d/ssh restart ).

• Connect securely with an SSH tunnel without requiring a password:

 "C:\Program Files\VistA\Putty\putty.exe" -ssh -i "C:\Users\user\Putty\id_rsa.ppk" -l client9260 -L 9201:127.0.0.1:9260 remoteserver.computer.xyz -P 22

Changing the SSH port

This is an optional step for more security and for networks where there are multiple servers on the network using SSH connections. (In some networking Configurations it is difficult for a router to know to which SSH server it should forward port 22 traffic). This method involves changing the port for the SSH (tunnel) traffic.

• See Changing the Astronaut SSH port

Securing your administrator password

• You should immediately change the administrator (sys.admin) password (i.e. Verify Code) from the installation default (vista!123), otherwise anyone reading these instructions would know the password of your installation. Duh. You can change this by a variety of methods.

• Login to the VistA server (in Linux) directly. You will be prompted to change the password the first time. If not, use the command:

sudo passwd sys.admin

• Login to TMG-CPRS or VistAConfig. The option to change the password at login appears:
• Change Verify Code: (ticked)

• In reality, you should change all the passwords of the sample users with which Astronaut VistA comes pre-populated, but since these passwords aren't displayed or published (in general), this is not as high a risk nor as immediate a priority.

Single shortcut startup

I don't like starting SSH and CPRS (or OpenVistA-CIS) with two separate commands (and I don't allow the AstronautSSH connection on bootup). If someone knows an easy way to start both at the same time, please add it. I use a somewhat "brute-force" method.

• Create a batch file for the Astronaut SSH startup, saved as AstronautSSH.bat in the C:\Program Files\VistA folder.

"C:\Program Files\VistA\Putty\putty.exe" -ssh -i C:\Users\user\Putty\id_rsa.ppk -l client9260 -L 9201:127.0.0.1:9260 remoteserver.computer.xyz -P 22

• Create a batch file (called ClientStart.bat in the C:\Program Files\VistA folder) to start whichever client (TMG-CPRS or OpenVista-CIS) is to be used. (The batch file when run by itself is able to allow a timeout of 7 seconds (to allow time for the PuTTY SSH connection to be made) before starting the client. When starting from a shortcut this timeout is ignored.) For OpenVistA-CIS:

rem timeout /T 7
cd "C:\Program Files\Medsphere\OpenVistA CIS"
"C:\Program Files\Medsphere\OpenVistA CIS\OpenVistACIS.exe" s=%ASTRO_LOCAL_HOST% p=%ASTRO_PORT%

or for TMG-CPRS:

rem timeout /T 7
cd "C:\Program Files\VistA\Common Files"
"C:\Program Files\VistA\tmg-cprs\CPRSChart.exe" S=%ASTRO_LOCAL_HOST%  P=%ASTRO_PORT% CCOW=DISABLE SPOOF-VER=%ASTRO_CPRS_SPOOF%

• In the Astronaut shortcut folder, create a new shortcut (I named mine AstronautComboStart) to start both files at once. Enter the names of both batch files in the Shortcut -> Target: field:

"C:\Program Files\VistA\AstronautSSH.bat" | "C:\Program Files\VistA\ClientStart.bat"

This has the effect of starting both batch files at the same time from the single AstronautComboStart shortcut. Even though the Client starts at the same time as the SSH tunnel, it takes me as long to enter my ACCESS CODE / VERIFY CODE (or LoginID / Password) as it does for the SSH tunnel to be negotiated, so it works out just right.

Update: It seems that TMG-CPRS does require the SSH tunnel to be already established, so the (as yet non-functional) timeout delay is required. Still searching for a method...

Installing in a protected environment

You may wish to install the Astronaut client package on a Windows computer whose access is restricted to certain administrators. The method involves installing Astronaut to the

C:\Documents and Settings\All Users\Application Data\VistA

folder on your Windows machine. This folder is generally not protected (or restricted to administrators) and can then be accessed by all users.

Environment variables may not be able to be changed on the computer by anyone other than an administrator. When installing without administrator privileges, the startup shortcuts must be changed so that environment variables are not used.

Change Astronaut SSH shortcut

The "Astronaut SSH" shortcut that is used to invoke the PuTTY SSH client uses a command line:

"C:\Program Files\VistA\Putty\putty.exe" -ssh -l %ASTRO_SSH_clientID% -pw %ASTRO_SSH_CLIENT_PASS% -L %ASTRO_PORT%:127.0.0.1:%ASTRO_PORT% %ASTRO_SSH_HOST%

The individual environment variables must be specified if you do not have privileges to specify environment variables. For example:

•  %ASTRO_SSH_clientID% -> client9260 (this is the default value)
•  %ASTRO_SSH_CLIENT_PASS% -> not#1sostrong (this is the default value)
•  %ASTRO_PORT% -> 9260
•  %ASTRO_SSH_HOST% -> 192.168.56.101 (use the IP address or URL of the installed VistA server)

The revised Astronaut SSH shortcut would therefore be:

"C:\Program Files\VistA\Putty\putty.exe" -ssh -l client9260 -pw not#1sostrong -L 9260:127.0.0.1:9260 192.168.56.101 -P 22

Change TMG-CPRS shortcut

The "TMG-CPRS" shortcut that is used to invoke the CPRS client uses a command line:

"C:\Program Files\VistA\tmg-cprs\CPRSChart.exe" S=%ASTRO_LOCAL_HOST% P=9260 CCOW=DISABLE SPOOF-VER=%ASTRO_CPRS_SPOOF%

The individual environment variables must be specified if you do not have privileges to specify environment variables. For example:

•  %ASTRO_LOCAL_HOST% -> 127.0.0.1
•  %ASTRO_CPRS_SPOOF% -> 1.0.26.66 (this is the default)

The revised TMG-CPRS shortcut would therefore be:

"C:\Program Files\VistA\tmg-cprs\CPRSChart.exe" S=127.0.0.1 P=9260 CCOW=DISABLE SPOOF-VER=1.0.26.66

Change Text client shortcut

The "Text client" shortcut that is used to invoke the Text client uses a command line:

"C:\Program Files\VistA\Putty\putty.exe" -P 22 %ASTRO_SSH_HOST% -l %ASTRO_textID% -pw %ASTRO_TEXT_PASS%

The individual environment variables must be specified if you do not have privileges to specify environment variables. For example:

•  %ASTRO_textID% -> text9260 (this is the default value)
•  %ASTRO_TEXT_PASS% -> not#1sostrong (this is the default value)
•  %ASTRO_SSH_HOST% -> 192.168.56.101 (use the IP address or URL of the installed VistA server)

The revised Text client shortcut would therefore be:

"C:\Program Files\VistA\Putty\putty.exe" -P 22 192.168.56.101 -l text9260 -pw not#1sostrong

Change VistA Config shortcut

The "VistA Config" shortcut that is used to invoke the VistA user Configuration utility uses a command line:

"C:\Program Files\VistA\GUI_Config\GUI_Config.exe" S=%ASTRO_LOCAL_HOST% P=%ASTRO_PORT% CCOW=DISABLE

The individual environment variables must be specified if you do not have privileges to specify environment variables. For example:

•  %ASTRO_LOCAL_HOST% -> 127.0.0.1
•  %ASTRO_PORT% -> 9260

The revised VistA Config shortcut would therefore be:

"C:\Program Files\VistA\GUI_Config\GUI_Config.exe" S=127.0.0.1 P=9260 CCOW=DISABLE

Change CPRS Query Tool shortcut

The "CPRS Query Tool" shortcut that is used to invoke the CPRS Query Tool uses a command line:

"C:\Program Files\VistA\CPRS_Query_Tool\CPRSQuery.exe" S=%ASTRO_LOCAL_HOST% P=%ASTRO_PORT% CCOW=DISABLE

The individual environment variables must be specified if you do not have privileges to specify environment variables. For example:

•  %ASTRO_LOCAL_HOST% -> 127.0.0.1
•  %ASTRO_PORT% -> 9260

The revised CPRS Query Tool shortcut would therefore be:

 "C:\Program Files\VistA\CPRS_Query_Tool\CPRSQuery.exe" S=127.0.0.1 P=9260 CCOW=DISABLE

Change other client module shortcuts

Don't forget to change the shortcuts for the other modules in a similar fashion:

• Group Notes
• GUI Mail
• Shift Handoff Tool
• Admin
• Vitals
• Vitals Manager

Installing to a USB flashdrive

A USB flashdrive is meant to be moved from one computer to the next, so environment variables will not be constant.

• See Installing the Astronaut client on a USB drive.

Using Astronaut with OpenVistA-CIS

If you have installed the Medsphere OpenVista-CIS client (for Windows) for use with the Astronaut OpenVistA server, then the Astronaut CPRS client package (for Windows) provides a convenient shortcut to start the OpenVistA-CIS client.

Astronaut -> OpenVistA CIS stub

For this to work, the PuTTY SSH connection to the server must already have been established (using the Astronaut SSH shortcut, as in the preceding sections).

Using Astronaut CPRS in Linux

• See this section.

About the clients

TMG-CPRS

Text Client

The Text Client is merely a direct SSH connection to the VistA server, using the text9260 user id. This allows the user to directly interact with the VistA server using a text interface. Most of the administration of the VistA server is done through this interface.

Because this is an independent SSH connection, the usual SSH connection (Astronaut SSH) does not need to be running.

CPRS Query Tool

Group Notes

GUIMail

Shift Handoff Tool

VistA Clinical Scheduling

VistA Config

Vitals

Vitals Manager

Admin

Sessions

Other Resources

• CPRS Overview
• [[CPRS Configuration - Adding an executable to the Tools Menu]]