Read Me

Remote Host Manager (RHM) Installation Instructions

Section 1: New installs.

0) Install prerequisites.  

   A) pdksh
      To determine if pdksh is already installed as ksh,
      Run: ksh -c 'echo ${KSH_VERSION}'
     
      If some variation of "@(#)PD KSH v5.2.14 99/07/13.2" is returned, it's 
      there.
   B) postgresql (at least 8.3.0 or newer)
   C) rsync

1) Grab rhm-VERSION.tgz from SourceForge.

2) Determine where RHM will live [ex: /usr/local/rhm], and untar it.  This is
   now the RHM_BASE ($RHM).

3) Tell RHM about your local configuration settings. Create conf/rhm.local from
   conf/rhm.local-template and set the following.
   
   RHM_BASE
   RHMDB_HOST
   RHMDB_USER
   RHM_SSH_KEY
   RHM_USER
   RHM_REPO_DIR

   RHMDB_PASS is special.  Having non-obfuscated passwords stored in plaintext
   is just wrong. So, to set this password, run

   perl -e 'print pack("u", "PASSWORD");'

   and set RHMDB_PASS to the result.  The RHMDB_PASS set in the local-template
   is an example. The pass used to generate that is "abc123", no quotes.
   
3a) Putting $RHM_BASE/bin into your path will make life easier.  Do it.

4) Now that pdksh is installed, RHM needs to know where it is, so the scripts 
   can find it.  If /bin/pdksh is there, done. Next step.

   Easy way: put a soft link in /bin/pdksh pointing to pdksh, if it's not 
   already there.
   
   Medium way: To let RHM try to do it for you, in the $RHM/conf directory, 
   run: find-pdksh.sh .  $RHM/bin/rhmhostlist first line should now point to
   the location of pdksh.

   Hard way: To manually change RHM to use pdksh in a location other than 
   /bin/pdksh. In $RHM/bin, replace /PATH/TO/PDKSH with the location of pdksh, 
   and run: 

   sed -ie "s%^#!/bin/pdksh%#!PATH/TO/PDKSH%g" rhm*

5) If this is a not new postgres install, steps G-I should be enough. Be safe, 
   dump the dataserver before adding in rhmdb.
  
  If this a new Postgres install, the following section might be helpful.

  A) Initialize rhmdb: initdb -D [/path/to/postgres/data/space/]rhmdb -E UTF-8 --no-locale
  B) Update listen_addresses in rhmdb/postgresql.conf if desired. Uncomment if
  setting this entry.
  C) Update host entry in rhmdb/pg_hba.conf to trust the necessary netblock.  
  See Note A about RHM and authentication/passwords.
  D) Start RHM postgres database: pg_ctl -D [/path/to/postgres/data/space/]rhmdb -l logfile start
  E) Login: psql -Upostgres
  F) Don't leave the postgres user without a password:  ALTER USER Postgres WITH PASSWORD '<newpassword>';

  Configure Postgres for RHM:

  G) Setup rhm_user: create role rhm_user with login password 'abc123';  
  See Note A about RHM and authentication/passwords.
  H) Create rhmdb: create database rhmdb with owner = rhm_user template = default encoding = 'UTF=8';
  I) Restore rhmdb schema: psql -Upostgres -d rhmdb < conf/rhmdb.schema.sql-$VERSION 

Make sure psql is in your path!

6) Create an SSH key for RHM to use. 

  A) If using a private SSH key in the $RHM_USER users account, setting an 
  empty passphrase might be a good idea. Sudo privilege limitations are your 
  friend.
  B) The private SSH key can be distributed to each RHM users local machine, 
  and via the magic of ssh-agent, a key with a passphrase is much more 
  palatable.

7) Setup a host for RHM to manage.

  A) On hosts that RHM will be managing, create the 'rhm' userid (UID 0, GID 0),
  add the public SSH key.  Add the host to RHM and verify connectivity with 
  rhmrun (sudo rhmrun HOST 'uname -a').  
 
  If connectivity doesn't work out of the box, things to check.
  I) rhm user is UID 0, and the home directory for the rhm user is owned by rhm.
  II) authorized_keys is in ~rhm/.ssh/ and was copied correctly from the .pub
  SSH key.  Make sure there are no CR/LFs in the key.
  III) Permissions on .ssh/ should be 700, authorized_keys should be 600 or 400.


Notes on installation.

A.  Using a password for the RHM_USER is probably a good idea.  RHM will work 
out of the box without one if postgres is setup to use auth method trust.  It 
is recommended to use auth method md5, and set the password in 5F above to 
something other than abc123.  

If you do this, edit $RHM/conf/rhm.local and update the RHMDB_PASS.  RHM will 
always try to authenticate with the RHMDB_PASS set in the conf file, even if 
postgres doesn't require it.

Section 2: Upgrading current install

1) Database changes. 

If upgrading from 0.1, the following DB changes will be necessary:
------

CREATE SEQUENCE rhm_action_log_id_seq
    INCREMENT BY 1
    NO MAXVALUE
    NO MINVALUE
    CACHE 1;

ALTER TABLE public.rhm_action_log_id_seq OWNER TO rhm_user;

CREATE TABLE rhm_action_log (
    actionid integer DEFAULT nextval('rhm_action_log_id_seq'::regclass) NOT NULL,
    hostname character varying(60) NOT NULL,
    commandname character varying(50) NOT NULL,
    realuser character varying(50) NOT NULL,
    commandargs text NOT NULL,
    commanddate timestamp without time zone NOT NULL
);

ALTER TABLE public.rhm_action_log OWNER TO rhm_user;

ALTER TABLE ONLY rhm_action_log
    ADD CONSTRAINT rhm_action_log_pkey PRIMARY KEY (actionid);
------

If upgrading from 0.2-beta10 or earlier, the following DB changes will be 
necessary:
------

ALTER TABLE ONLY rhm_action_log
	ALTER COLUMN commandargs TYPE text;
------

During this alteration, Postgres might timeout waiting for the statement to 
finish. If this happens, changing the work_mem setting will fix it.

	postgres=# show work_mem;
	work_mem
	-
	2MB
	(1 row)
	postgres=# set work_mem=32768;
	SET
	postgres=# show work_mem;
	work_mem
	-
	32MB
	(1 row)

Now re-run the ALTER TABLE.

2) Code changes.

If upgrading from 0.1:

Copy the new bin/ lib/ over top of the existing $RHM/bin and $RHM/lib.

Make backup of existing $RHM/conf/rhm.conf.

Migrate existing $RHM/conf/rhm.conf settings to new conf/rhm.conf (won't 
change that often) and conf/rhm.local.  To create conf/rhm.local, copy
conf/rhm.local-template to conf/rhm.local and update the settings.

See if Step 4 in the New Install section applies.

Section 3: Get help.

For problems, email the project admins through SourceForge or Dave directly
at rhm at ginch dot org.

Section 4: Changelog

0.1 (r50):
First release. Woah nelly. Basics. 
Host add, del, list; Tree add, del, list, query; Rsync and run utilities 
 released. 
Conf file, initial schema and README.  
Docs on Wiki began, all utilities are documented, with runtime examples.
     
0.2 up to beta10 (r80): 
README updated.
Changed default to /bin/pdksh for all utilities.
Updated schema to include DB based RHM transaction logging. Still need tool
 to retrieve stored data.
Updated all RHM tools that change RHMDB or touch a remote host to log to RHMDB.
Cleaned up several exit calls to close DB connections cleanly before exiting.
Added this changelog.
Added ability to run RHM commands from anywhere, as long as $RHM/bin is in the
 path.
Added password obfuscation to $RHM/conf/rhm.conf. Updated README to include 
 instructions on how to created obfuscated password entry.
Fixed missing clause in rhmrsync where if more than 1 tagged tree matched a 
 prerequisite, it just skipped it without notifying the user.
Fleshed out documentation for tree, tag, prerequisite, pre and post script 
 support on the wiki.
Changed the way rhm.conf works - now calls a rhm.local file with config options
 that shouldn't change between versions, allowing rhm.conf to still change as
 necessary.
Added rhmnewver tool to make it easier to generate a new tag within a tree.
Added rhmtreeup tool for updating tag versions on trees already tagged to a host.
Cleaned up closing DB connection bugs.
Fixed missing executable perms on rhmnewver.
Fixed exit code catch on rhmrsync for rsync failure.
Added exit code catch on rhmrun for failed SSH connection/execution.
Fixed bug in rhmtreeup with multiple host regex matches when the tree is not 
 tagged to matching hosts.
Fixed bug in rhmrsync related to pushing the same single tree to multiple hosts.
Added rhmtreelatest tool to easily find the latest version of a tree, based on
 RHM convention.
Added login to use "latest" in rhmtreeadd and rhmtreeup, uses rhmtreelatest tool
 to do the heavy lifting.
Fixed rhmhostclone bug where if the DST FQDN matched multiple hosts in RHMDB, 
 all matching hosts would be affected, not just the one intended.
Fixed missing help/usage output in rhmtreeup related to using -v latest.
Added dryrun mode (-d) to rhmrsync.
Added magic to svn to track versions in each file.
Added rhmlogquery to report on the rhm_action_log table content.
Added [latest=TAGVER] to the action log entries for treeadd/treeup when using
 -v latest so the tag that latest resolved to gets logged.
Wiki docs updates.
Fixed logging error in rhmrsync where a tree was not tagged to a host.
Re-ordered the logic in rhm.conf so that rhm.local gets sourced at the [almost]
 end, allowing the user to override automatically generated settings.
Fixed bad regex in rhmtreelatest, missing boundaries.
Added user configurable timeout value to rhm.local-template.
Fixed missing cron flag check in rhmrsync at confirmation prompt time.
Fixed cosmetic error in rhmrun when not matching any hosts.
Added cleanup.sh script functionality to rhmrsync.
Fixed host IP resolution for displaying when calling pre/post/cleanup script to
 only use the first response from DNS.
Fixed bug where running post script remotely doesn't capture exit code.  Now if
 exit code from post script is non-0, rhmrsync stops, and returns an error.
Added additional logging to treeup to note the tag being replaced in the DB 
 based change log.
Added check for extra unparsable args in newver.
Fixed logging bug in rhmtreeadd related to using latest.

0.2 beta 11:
Added negation flag to treequery. Display matching hosts w/o tree tagged.
Added better logging to treedel for -t tree and -t all.
Fixed bug in rhmnnewver when there is no dir with expected convention.
Added optional tree version to rhmtreequery to further limit searches.
Changed logic in rhmlogquery to take host regex and turn it into exact matches
 to speed up the DB query.
Changed order of field output in rhmlogquery to allow very long commandargs to 
 be at the end, and not mess up the display for other rows.
Added check for rhmtreeadd and rhmhostadd to see if called via sudo, if so, log
 real user name.
Added quiet mode and no-hostname-prepend mode to rhmrun. 
Created rhmtreediff - make it easier to visually compare tagged trees between
 2 hosts. Created docs for rhmtreediff on SourceForge Wiki site for RHM.
Changed commandargs type in RHMDB rhm_action_log table to be text (unlimited
 length) in .sql file for new installs, and updated README instructions for 
 altering existing tables.

0.2 beta 12:
Fixed rhmnewver bug related to determining latest tree version automatically
Added entry to README for dealing with conversion of action_log table to new 
 column type.
Removed test for which using a known failed binary.

0.2 beta 13:
Fixed rhmhostclone bug related to forcing the command w/o a prompt
Fixed rhmhostclone bug related to -h and minimum number of args (check was in 
 the wrong place)
Fixed cosmetic usage output in rhmtreedel