====================== VNS Installation Guide ====================== updated 3/26/91 Copyright (c) 1991, Groupwork Systems, Inc. Need help? ---------- Call Kevin Long at 713-798-6116 or email to klong@bcm.tmc.edu. Introduction ------------ This guide describes the installation process for installing the "flat file" version of the VNS suite of software on a SUN SPARC-architecture machine. Let's dive right in. Setting up the Accounts ----------------------- The VNS system requires installation under the account "vns". This approach allows the "vns" user to control and maintain the VNS system, and creates a user separate from all others with the permission to create databases, add users, etc. *This person is the VNS Administrator.* Create a mail alias called "vns-bugs" and "vns" and point the mail to this person. VNS users that choose to invoke the bug-logging feature of the product will generate mail addressed to vns-bugs. Some optional stuff--- It is a good idea to log in a file the mail that is being sent to vns-bugs. This can be done with an entry in /etc/aliases like: vns-bugs: /VNS/incoming-bugs,vns (substituting the value of ~vns for VNS above). Check with your system administrator about adding the accounts and mail aliases. When done, tar off the the software provided on this tape into the directory "~vns/apps". We used the following command to create our tar file: tar cvfb - 20 *filenames* | rsh *host* dd of=/dev/rmt0 obs=20b This is straight out of the tar man page. To extract, make sure you use a blocksize of 20 also. For example, on a machine with a QIC-24-capable cartridge tape drive: venus% pwd [~vns/apps/system] -- UNIX will substitute the real pathname here venus% tar xvfb /dev/rst8 20 ...messages from tar... You will find the following directories and files are installed: INSTALL app-defaults/ - certain application defaults files are here bin/ - where the end-user-accessible binaries are located config/ - printer configuration information docs/ - srvlib.doc describes the API for writing your own programs that manipulate notebook data examples/ - some example programs that get info from the dbs include/ - header files for persons using the API lib/ - libraries for persons using the API system/ - programs for managing your vns installation You've got a flat-file version of the VNS that doesn't require Sybase, Ingres, etc. It uses ndbm, a common package of relational routines available on many UNIX machines. You need to have a license for ndbm on your UNIX machine to use the VNS. Most UNIX installations seem to have this, including Sun and Solbourne platforms. Do a "man dnbm" or look in /usr/lib and verify that libdbm.a is there. If it is, then you have the library. If you've licensed what you've got, then you're set. About the VNS Architecture -------------------------- The VNS is a 3-layered system. At the bottom layer is the database, managed by ndbm. In the middle is an agent, called dbsrc, a traffic cop of sorts, that is the intermediary between the database and the top layer. The top layer is the end-user programs, including the VNS X11 binary. To set up the environment, you need to install each of these three logical layers and do some tidying up. Here are the steps: --------------------------------------------------------------------- (1) Create a new userid "vns". Make sure that this userid is constant and unique across all systems from which you will want to rlogin or rsh as vns. Everything is owned by and accessible from the vns account, so take care in using group and world permissions. Give vns an account and a home directory. (2) (optional) Create a userid vnsguest. We'll try things out and edit the .cshrc and .login in this directory first before editing everyone's setup files. Give it the c-shell as its default shell. (3) Decide on a location for the VNS data. We recommend ~vns/data. This directory must be owned by vns, and have rwx------ permissions set. (4) Select a name for your database. You can have more than one database. Each one has its own set of valid users, its own set of notebooks, pages, and objects for those users. It is completely separate from any other database you might create later. For now, create just one database. Give it a meaningful name for your group or project and tag "_VNS" onto the end of the name. Here are some we've created: mbir_VNS (Molecular Biology) neuro_VNS (Nuroscience) acct_VNS (Accounting) After selecting a name, a subdirectory using this name should be created in your data directory. For example: venus% whoami vns venus% cd ~vns/data venus% mkdir smith-kline_VNS venus% chmod 700 smith-kline_VNS venus% ls -al total 3 drwxrwxr-x 6 vns 512 Feb 22 16:51 ./ drwxrwxr-x 9 vns 512 Mar 14 08:19 ../ drwxr-xr-x 7 vns 512 Feb 12 17:52 smith-kline_VNS/ (5) Now that we have a location and a database name, we now run the install program for setting up the database files to allow startup of the VNS server (dbsrv). The install program is located in ~vns/apps/system and is called "install_ndbm". The program takes these three arguments: database directory - path chosen in (1) above, e.g. ~vns/data, NOT ~vns/data/smith-kline_VNS database name - database name chosen above e.g. smith-kline_VNS initial username - the first user - "vns" If you leave off the arguments, install_ndbm will prompt you: venus% install_ndbm Usage: install_ndbm An example is shown below for invoking the install_ndbm program: venus% install_ndbm ~vns/data smith-kline_VNS vns This program creates the database and adds the initial author or user to the database. This allows us to start the VNS agent (the middle layer) and proceed with running the VNS program (top layer), adding additional users, etc. (6) Now that we have initialized the database for the flat-file version we are ready to startup the middle-layer VNS agent. We call it dbsrv for database server. The VNS data server is located in ~vns/apps/system and is called "dbsrv_ndbm". This particular version of dbsrv uses the "ndbm" functions for accessing the flat-file version created with install_ndbm program. The "dbsrv_ndbm" program takes 3 arguments: database directory - path chosen in (1) above, e.g. ~vns/data, NOT ~vns/data/smith-kline_VNS port # - The UNIX port number on which dbsrv will wait and listed for connections from users needing to get at the data, including the VNS. Try 6721 for now. Your system manager can give you an alternative number if this port is used by someone else already. database name - selected above, e.g. smith-kline_VNS An example of invoking dbsrv_ndbm follows. Note that you must be vns: venus% whoami vns venus% pwd [~vns/apps/system] -- UNIX will substitute the real pathname here venus% dbsrv_ndbm Warning: This program will expire on 5/1/91. dbsrv_ndbm(1.1.0): protocol(1.3) Usage: dbsrv_ndbm [ ... ] venus% dbsrv_ndbm ~vns/data 6721 smith-kline_VNS & Warning: This program will expire on 5/1/91. dbsrv_ndbm(1.1.0): protocol(1.3) dbsrv: data directory: ~vns/data port: 6721 Loading: smith-kline_VNS dbsrv: message: entering main loop Notice that the program is executed as a background process. This is important. Also note the last message: entering main loop. This is CRITICAL. Do not logout as vns until you've seen this message. See "Notes about shutting things down" for other hints. No matter how many copies of the VNS are running on your network, and no matter how many machines on which they may be running, you must only have ONE copy of dbsrv running at a time for a particular database. Later, if you create multiple databases (by using install_ndbm with a different database name), you have an option. You may create multiple agents, each on their own unique unix port, each of which is assigned to a unique subset of the various databases, or you may have a single agent (on a single port) that handles requests for all databases. This is why the usage statement returned by dbsrv_ndbm shows the option of specifying multiple databases on the command line. (7) Your are now ready to run VNS. There are files that we'll customize next to help simplify the process of running the vns for the general user, but for now, we'll start up the vns with all of its command-line options to ensure that it runs. The same options are always necessary for programs wishing to communicate with the agent (dbsrv): server - the host name of the machine on which our dbsrv agent is listening (venus, in our example) port # - The UNIX port number on which dbsrv waits. This should be 6721. database - Selected above. e.g. smith-kline_VNS venus% vns -port 6721 -database mbir_VNS The complete example, then, is this: venus% cd ~vns/apps/bin venus% vns -server venus -port 6721 -database smith-kline_VNS You may optionally run this in the background. You should see a command panel appear with "Notebook", "Session", "Quit". This completes the administration tasks for installing the VNS. The next section covers configuring a sample account (vnsguest), and adding new users to our database of persons authorized to run the VNS. Configuring the Application Defaults File for VNS: --------------------------------------------------------------------- When the "vns" command is given at the command prompt, the vns will attempt to read certain default values for command line arguments from a file in ~vns/apps/app-defaults, given that the account has been properly configured to look here (more on this later). This file, called "Vns", is located in the directory ~vns/apps/app-defaults. There are several resources that can be used to configure the VNS, but only three will be discussed here. They are: Vns*server: Vns*database: Vns*port: An example configuration for these parameters is shown below based on the example installation described above: Vns*server: venus Vns*database: smith-kline_VNS Vns*port: 6721 You should edit this file (as vns) and make the changes accordingly for your site. Working with VNS on a Network: --------------------------------------------------------------------- One of the great features of VNS is its flixibility in network situations. The VNS accepts two command line arguments that provide these features: -server : This allows the vns to connect to a copy of dbsrv that is running on another machine. This allows the VNS to run locally, say on a SPARC station 1+, while communicating with the agent running on another computer, say a SPARCserver. In this sense, the processing requirements needed to run the VNS are truly distributed. -display : This option, common to most if not all X programs, allows a program to run on the CPU of one machine, while using the display, keyboard, and mouse of another machine. For example, the VNS program can be run on a high-speed server while redirecting the X display to a local X terminal. This is also very useful if you wish to display the VNS on a non-Sun machine. You can also combine the two and have the VNS communicating with a remote copy of the dbsrv agent while the display is redirected to some other node on the network! Here is an example of how a user on machine "saturn" can connect with the VNS server on machine "venus": saturn% vns -server venus -port 6721 -database smith-kline_VNS If the user wished to redirect the X output to another display, say on machine "mars", the user could do the following: saturn% vns -display mars:0 -server venus -port 6721 -database mbir_VNS Setting up the vnsguest account ------------------------------- Whether you chose to create the vnsguest account or not (it was optional), you must take the following steps for each of your users in order for them to use the VNS. Give vnsguest the .cshrc and .login files you normally give to new users. We recommend you make these changes for everyone once you've verified they work for vnsguest. Add to the .cshrc file the following environment variables: setenv VNS ~vns/apps setenv XUSERFILESEARCHPATH $VNS/app-defaults The VNS variable will be used later in a path definition. The second variable tells X where to look for app-defaults information. If XUSERFILESEARCHPATH is already a defined environment variable in your environment, then add the $VNS/app-defaults definition to it. e.g. setenv XUSERFILESEARCHPATH ./%N:$HOME/app-defaults:$VNS/app-defaults We also need to add two things to the path definition. Either edit the path definition manually, or drop this in after other path definitions in the .cshrc: set path=($path $VNS/bin) Additionally, for the vns account, you should add $VNS/bin/system to the path. e.g. set path=($path $VNS/bin $VNS/bin/system) This allows the vns user to access the system routines like dbsrv and add_user. To test everything, log out, and log back in as vnsguest, and try typing "vns" at the command prompt. If the VNS comes up, then you're ready to propogate these changes to others. Adding new users ---------------- Only users listed as authorized in a particular VNS database may access the VNS. Users who attempt to run the VNS before they've been added by the VNS Administrator will see a message something like this: jdoe@venus% vns Virtual Notebook System (vns2.1.0) Copyright (c) 1990 Baylor College of Medicine Error(srv_init): connection denied: Invalied author for specified database: 999 ******************************************* (emphasis added) vns: error: cannot communicate with dbsrv server: venus port: 6721 database: smith-kline_VNS jdoe@venus% vns The line above the asterisks is the important one here. Users can never, ever be removed from the database. Keep that in mind.. To add a new user, log in as vns, and run the add_user command. The example below shows us adding jdoe as an authorized user: venus% whoami vns venus% pwd [~vns/apps/system] -- UNIX will substitute the real pathname here venus% add_user Usage: add_user [ ... ] venus% add_user venus 6721 smith-kline jdoe ...perhaps a message from add_user... venus% Note that unlike other commands, presently the add_user command doesn't require the -database, -server, or -port prefixes before its arguments. Also, the arguments must be specified in precisely the order shown. Notes about shutting things down -------------------------------- If something happens that causes dbsrv to die, you must kill off all copies of VNS and any other programs that have connections open to the port on which dbsrv was listening before dbsrv can be restarted. If you don't do this, you'll see a message like: venus% dbsrv_ndbm ~vns/data 6721 smith-kline_VNS dbsrv_ndbm(1.1.0): protocol(1.3) dbsrv: data directory: ~vns/data port: 6721 Loading: smith-kline_VNS ...time passes... dbsrv: error: Could not establish listening sock venus% Killing off dbsrv is a simple matter of running kill_server or kill -9'ing the process. The VNS saves things as it goes along, so your users will only lose at most their last operation if dbsrv dies.