Proposal for VistA Standard Base (VSB) Specification/Guidelines Version 0.9 Release Candidate 8

Principle Author: Ignacio Valdes, MD, MS, ivaldes@hal-pc.org Contributors: Many.

Abstract: To enable and facilitate the creation of standard VistA management methods, documentation and tools for machines that contain approximately 1 to 5 instances of VistA on the same machine running Linux using GTM. More efficient, higher uptime and larger installations such as for an ASP type deployment should follow the VistA ASP Base (VAB) Specification: http://docs.google.com/View?docid=dd5f3337_232jhhvdvdj

Methods: Review of several VistA Appliances, review of multiple vista layouts, Nancy Anthracite's documentation, Linux Standard Base recommendations, File system heirarchy http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard, public discussion, comment and feedback on Google Group's Hardhats list of which over 150 comments where made. Public community and private anonymous vote on the Google Groups Hardhats list to settle the question of preferred <base_dir> to endorse the standard.

Changes: Some changes to port listener filenames.

Preferred by the community <base_dir> is /opt for alternative <base_dir>'s see 15)

Simple Install directory layout:

/opt/lsb-gtm/<version>_<platform>              # default for gtm, owned by bin, all uppercase routines.
/<base_dir>/<branding>vista/<instance>
/<base_dir>/<branding>vista/<instance>/backup     # Can be mount point. Backups that are not journals.
/<base_dir>/<branding>vista/<instance>/bin        # for server controller type software.
/<base_dir>/<branding>vista/<instance>/bin/run.sh # Bhaskar'sconvention, run an instance.
/<base_dir>/<branding>vista/<instance>/bin/vistastart.sh # Bhaskar's convention.
/<base_dir>/<branding>vista/<instance>/bin/vistastop.sh  # Bhaskar's convention.
/<base_dir>/<branding>vista/<instance>/bin/vistactl.sh   # Manual start, stop, restart
/<base_dir>/<branding>vista/<instance>/bin/vista_client-port-<namespace>.sh  # Nancy's convention, pointed to by vista_<instance>-client-<namespace>.conf
/<base_dir>/<branding>vista/<instance>/bin/vista_client-port-<namespace>.conf  # Nancy's convention configuration for xinetd, sym-linked to /etc/xinetd.d/
/<base_dir>/<branding>vista/<instance>/bin/env # bash compatible gtm/VistA environment variables.
/<base_dir>/<branding>vista/<instance>/doc     # all documentation resides here.
/<base_dir>/<branding>vista/<instance>/etc        # Version, release and other configuration information.
/<base_dir>/<branding>vista/<instance>/etc/patch_listing.txt # Optional listing of patches for this instance.
/<base_dir>/<branding>vista/<instance>/etc/vista.conf  # contains version, release and other config information. XML format.
/<base_dir>/<branding>vista/<instance>/e<xport>   # Export files from VistA.
/<base_dir>/<branding>vista/<instance>/g<lobals>  # Can be a mount point to a different physical device.
/<base_dir>/<branding>vista/<instance>/images     # Can be mount point for patient photos, scanned documents.
/<base_dir>/<branding>vista/<instance>/i<mport>   # Import files to VistA such as KIDs files.
/<base_dir>/<branding>vista/<instance>/j<ournals> # Can be a mount point to a different physical device.
/<base_dir>/<branding>vista/<instance>/lib        # Libraries.
/<base_dir>/<branding>vista/<instance>/log        # Logs, symlink to /var/log
/<base_dir>/<branding>vista/<instance>/log/vista/vista_port-gui.log        # Log file, symlink from /var/log
/<base_dir>/<branding>vista/<instance>/o<bjects>  # Object files.
/<base_dir>/<branding>vista/<instance>/p<atches>  # KIDS patches
/<base_dir>/<branding>vista/<instance>/r<outines> # Usually mumps routines, see additional heirarchy 13) below
/<base_dir>/<branding>vista/<instance>/web        # Future web items.
/etc/init.d/vista-<instance>                      # Automatic start stop startup handling. Symlinked to bin vistactl.sh
/etc/xinetd.d/vista_<instance>-client-<namespace>  # setup listening port for client such as CPRS, Symlinked to ./etc.

Where:

<base_dir> -- Preferred base_dir default to be voted on about Friday. Can be /opt, /var/opt, /opt/mumps as well as 'single-user' mode /home/<userid>, /opt/mumps (see 1 below)
<branding> -- 'world', 'open', 'vx' etc, MUST be preceeded or followed by 'vista' as in <branding>vista.
<instance> -- can be multiple instances. Parent and child instances via symlink okay. See 4) below for default names.
g<lobals>, r<outines>, o<bjects>, j<ournals>, e<xport>, i<mport> are defaulted to g, r, o, j, e, i, with full name available only if the vista release supports it. Symlinks can be used.

1) <base_dir> preferred is /opt
2) Good practice for /backup and j<ournals> is that they should be symlink or a mount point on a different physical media. Directories that can be mount points are:
 a) /<base_dir>/<branding>vista/<instance>/g<lobals>
 b) /<base_dir>/<branding>vista/<instance>/backup     # Backups that are not journals.
 c) /<base_dir>/<branding>vista/<instance>/j<ournals> # Can be a mount point to a different physical device.
 d) /<base_dir>/<branding>vista/<instance>/images     # Can be mount point for patient photos, scanned documents.

3) Default port for clients such as CPRS listening: 9260 Production, 9261 Training, 9262 Development

4) Defaults names for <instance>: production, training, development, <customer name>

5) All documentation explicitly converted from Microsoft format cr/lf to Unix/Linux format before posting.

6) Standard use of tar.gz format for bundling of files and residing on Sourceforge.

7) Default user id: vista, default group id: vista

8) /var/log  for logs, symlinked from /<base_dir>/<branding>vista/<instance>/log

9) /tmp for temp files

10) Use /etc/skel and /etc/profile.d for global environment settings where appropriate.

11) Use the suffix .sh on scripts that are shell scripts.

12) GT.M journal files are written to the j<ournals> directory.

13) If supported by VistA release, additional r<outines> subdirectories first proposed by J. Tai with modifications:

  The routines directory contains MUMPS routines (.m files).  No routines are stored in the routines directory itself; the routines   are stored in subdirectories that reflect the origin of the routine.

  /<base_dir>/<branding>vista/<instance>/r<outines>/development
  /<base_dir>/<branding>vista/<instance>/r<outines>/hotfixes
  /<base_dir>/<branding>vista/<instance>/r<outines>/customer
  /<base_dir>/<branding>vista/<instance>/r<outines>/vendor
  /<base_dir>/<branding>vista/<instance>/r<outines>/foia

  Where:
    * development – code that is under development; this directory should always be empty in production environments
    * hotfixes –  code not yet part of any Kernel Installation and Distribution System (KIDS) build or other distribution
    * customer –code that is part of a customer-specific KIDS build
    * vendor – code from third-party vendors, e.g., the Victory Programming Environment
    * foia – unmodified code from the U.S. Department of Veterans Affairs (VA)
    * version_patch_info -- Information on versions and patches on the system.

14) vista.conf will be WC3 xml compliant. Variables in env and vista.conf should be identical for the same information. Simple example vista.conf file:
<xml>
  <vsb_compliant value="1">         # VistA Standard Base Compliant? 1=yes, 0=no.
  <vab_compliant value="0">         # VistA ASP Base Compliant? 1=yes, 0=no.
  <gtm_versioning value="0">        # Higher uptime gtm_versioning subdirs used? 1=yes, 0=no.
  <vsb_version value="0.9">
  <vista_version value="WVEHR_1.0">
  <vista_release value="06-08">
  <gtm_version value="53003">
  <base_dir value="/opt">
  <gtm_dist value="/opt/lsb-gtm/V53003">
  <gtm_vista value="/opt/worldvista/EHR">
  <groupid value="vista">
  <ownerid value="vista">
</xml>

15) Alternative <base_dir>
  a) User-mode VistA: <base_dir> can be /home/vista<user-id> with owner and group vista<user-id>. The user-id must contain the word 'vista' or simply be 'vista' for VSB compliant tool discovery to work.

  b) Splitting between /var/opt and /opt: Strict interpretation of Linux Standard Base allows for splitting between /opt for files that do not change and /var/opt for files that change on a regular basis such as the g<lobals> subdirectory. This should be symlinked appropriately to the 'Simple Install directory layout' heirarchy above so that VSB compliant tools will work.

  c) <base_dir> /opt/mumps/* may be used instead of /opt as long as the rest of the 'Simple Install directory layout' above is followed.

16) Higher uptimes when upgrading or switching gtm versions can be achieved by a directory structure that includes: /<base_dir>/<branding>vista/<instance>/gtm_<version>/* the delimiter 'gtm_' must be included for VSB compliant tool discovery to work. If used, gtm_versioning value should be set to 1.

17) Each instance should have its own default group and id to avoid conflict with other instances running on the same machine. id and group for the instance should be <branding>vista<instance>.

18) Standard env file. NOTE: The VALUES on the right are EXAMPLES only. The variables NAMES on the left are what is important.

#!/bin/bash
# Group that needs to be changed if relocated or port changed.
export vista_instance="EHR" # Like EHR, training, dev.
export vista_port="9260"           # Listening port for clients like CPRS.
export vista_port_old_rpc="9210"           # Listening port for old RPC.
export vista_path="/opt/worldvista/EHR"   # Path to this instance like
/opt/worldvista/EHR.
export gtm_dist="/opt/lsb-gtm/V53003"        # Path to gtm such as
/opt/lsb-gtm/V53003
export vista_group="vista"
export vista_owner="vista"
export m2web="/opt/worldvista/EHR/web/m2web"
export ewd_path="the_ewd_path"
#
export vista_version="WVEHR_1.0"
export vista_release="06-08"
export gtm_version="53003"
export ewd_version="762"
export vsb_compliant=1
export vsb_version="0.9"
# MD5 Library external-call table
export GTMXC_md5="$vista_path/web/m2web/xc/gtm_md5.xc"
#
export vista_home="$vista_instance"
export gtm_path=$gtm_dist
export gtm_sysid="$vista_owner"
export gtm_vista="$vista_path"
export gtm_log="$gtm_dist/logs"
export gtmgbldir="$vista_path/g/mumps.gld"
export gtmroutines="$vista_path/o($vista_path/web/m2web
$vista_path/web/ewdapps/routines $vista_path/r) $gtm_dist"
alias GDE="$gtm_dist/mumps -r GDE"
alias rundown='$gtm_dist/mupip rundown -r "*"'
alias GTM="$gtm_dist/mumps -direct"
alias gtm="$gtm_dist/mumps -direct"
alias mupip="$gtm_dist/mupip"
alias gde="$gtm_dist/mumps -r ^GDE"
alias GDE="$gtm_dist/mumps -r ^GDE"
alias lke="$gtm_dist/lke"
alias dse="$gtm_dist/dse"
alias LKE="$gtm_dist/lke"
alias DSE="$gtm_dist/dse"