Rush Logo Rush Mac Install Instructions
(C) Copyright 1995,2000 Greg Ercolano. All rights reserved.
V 102.43 07/18/07

Mac OSX Install Instructions




   Installing Rush  
    0) Be sure your network meets these prerequisite requirements.

      This is essential to ensure a stable network so Rush can operate reliably.
      It's important machines don't change their hostnames or IP addresses after normal reboots, and that IP address lookups are consistent throughout reboots which a consistent local DNS (or /etc/hosts) configuration provides.

    1) Make sure your /etc/hostconfig file has a "HOSTNAME=your_hostname" entry

      This disables the 'hostname.local' and Rendezvous/Bonjour stuff that causes instability in production networks.

      For example, if your machine is named "tahoe", then make the entry:

        HOSTNAME=tahoe

      If the entry doesn't already exist, add it as a new line. If there's an existing entry in the file that reads "HOSTNAME=-AUTOMATIC-", replace it with the above.

      After making your changes, reboot.

      There should *NOT* be a '.local' in your entry, as that's a special domain that Mac uses for Rendezvous/Bonjours.. use some other domain name, if you specify a domain name at all. Be careful when editing /etc/hostconfig:

      • Use an ascii text editor to ensure no font formatting characters get into the file.
      • Don't make typo's! This file is parsed during boot.

    2) Choose a local directory to install rush.
      /usr/local/rush is recommended. If /usr/local doesn't exist, create it first.

      Open a terminal window, and login as root, and extract the tar file as:

        Extracting Rush Tar File 
            cd /usr/local
    gunzip -c /tmp/rush-xxxxx.tar.gz | tar xvfp -

      The tar 'p' flag is important! It will preserve the permissions needed to make the daemons run properly.

      To install Rush on a large network, first complete all the steps to install on one machine, then use the Network Install instructions to install on all the rest of the network.

      If you want to install rush in another location, refer to these instructions.

        WARNING: As with all daemons and their config files, do *not* install the rush directory or binaries on an NFS drive.
        Keep rush binaries and config files local on each machine. Here is why.

    3) Configure the /usr/local/rush/etc/hosts file

      It should contain the names of all hosts that participate in rendering. See Hosts File for descriptions of each field.

    4) Install the license that was emailed to you into /usr/local/rush/etc/license.dat.

    5) Security issues and special configurations.

    • Disable the OSX firewall.
      Apple now includes a firewall that is default 'on' in some versions of OSX which, if left enabled, will prevent Rush from being able to communicate with remote machines.

      Disable the the firewall via:

      System Preferences | Sharing | Firewall | Off

      Or, if you want the firewall enabled, make sure TCP and UDP port 696 is left open in the 'Settings' menu. If you want Rush to be able to send email on job completions, you'd better allow port 25 to be able to reach your mail server as well.

    • If security is a concern at your site, carefully review the Admin FAQ on Security for security precautions and configuration.

    • (OPTIONAL) Review the /usr/local/rush/etc/rush.conf file.
      For most situations the defaults suffice, but sometimes it pays to be pedantic.

    • (OPTIONAL) Register your settings for serverport in /etc/services or equivalent (NIS, NetInfo, etc). See serverport for an example services entry.

    6) Run the install script.

      /usr/local/rush/etc/bin/install.sh

      Watch for any errors in the output.

    7) Start the daemon, and test it.

      Start the daemon by invoking the boot script:

        /usr/local/rush/etc/S99rush start

      Then open a *new terminal window* and use 'rush -ping' to verify the daemon's running:

        Testing The Daemon 
        
  % rush -ping
  yourhost: RUSHD 102.42 PID=XXXXX   Boot=10/15/00,03:25:49  Online, 0 jobs, 0 procs
  %

      If you get an error:

        % rush -ping
        yourhost: can't open port lock file '/usr/local/rush/var/nextport': Permission denied

      ..then you either weren't running as root when you ran the install script, or somehow missed running the install script (step #6). To fix this, make sure you are logged in as root when doing the install.

      If you get a different error, check the daemon logs for problems, eg: 

      
     tail -f /usr/local/rush/var/rushd.log

      To test if the daemon is working, you can run this test submit script, just to verify jobs can be started, listed, and dumped:

        /usr/local/rush/examples/test-submit

      To submit a real job, similar to what TDs use, you can run this test which includes complete instructions for someone who has never used rush before.

    8) Install the submit scripts for the users

    9) (OPTIONAL) Miscellaneous configurations

    • Configure the /usr/local/rush/etc/templates file.

      You can customize the output of 'rush -tss' and 'rush -trs', useful for advanced users who want to quickly create their own submit/render scripts.

    • Configure the /usr/local/rush/etc/.submit and /usr/local/rush/etc/.render files.

      These files are sourced by the default Submit Script and Render Scripts respectively.

    • Accounting log rotations.

      Rush maintains a history of cpu utilization information in the /usr/local/rush/var/cpu.acct file. If you don't want this file to grow too large, you might want to have it rotated on a monthly basis, eg: 

           0 0 1 * * root /bin/mv /usr/local/rush/var/cpu.acct /usr/local/rush/var/Ocpu.acct
      You may want to then push the rotated file through an accounting filter to keep tabs on cpu usage for the network. This is left as an exercise to the reader.

    Once you have things working on the first machine, then you can easily install rush on the rest of the machines. See 'Network Install' below..

   Network Install  
    To install rush on the rest of the network (assuming you've got it working on one machine), you will want to rcp(1) the /usr/local/rush directory to all the machines, start the daemons, and verify they're running.

    FIRST, make sure *all* the hostnames you will be installing on are already configured in the /usr/local/rush/etc/hosts file.

    Then, copy the entire /usr/local/rush directory to the rest of the machines and start the daemons with these commands:

      Rush Network Install Commands 
      
    foreach i ( host1 host2 host3 .. )
	echo --- $i
	rcp -rp /usr/local/rush ${i}:/usr/local/rush
	rsh $i /usr/local/rush/etc/bin/install.sh 
	rsh $i /usr/local/rush/etc/S99rush start
    end

    Now verify all the daemons have started. 

    
    rush -ping +any          # pings all daemons in rush/etc/hosts

   Uninstalling Rush   

    1) Kill the daemon:
           
	   killall rushd
	   
    2) Remove the entire /usr/local/rush directory:
           
	   rm -rf /usr/local/rush
	    
    3) Remove the boot script:
           
	   rm -rf /Library/StartupItems/Rush

   Network Install: Disk Cloning  
    If you are setting up a large farm, often you set up the software on one machine, then 'clone the disk' to all the other machines.

    With Rush, the idea is to ensure the /usr/local/rush/var directory is empty on all the cloned disks, so that the daemons on the cloned machines don't inherit stale files from the master (eg. old accounting logs, job checkpoint files, daemon logs with irrelevant error messages), as these files will negatively interfere with the cloned machines:

      Preparing A Master Disk To Be Cloned
        The following commands will prepare the cloning 'master disk'; shut down the rush daemon on this machine
        so that all files in the /usr/local/rush/var directory are closed, then clear out the 'var' directory
        completely by removing and re-creating it. Run these commands as root:
        
    /etc/init.d/rush stop
    rm -rf /usr/local/rush/var
    mkdir -m 755 /usr/local/rush/var

        The disk is now ready to be cloned.

        You can shut down the machine, but do not reboot it using this drive, or the daemon will start automatically,
        and the /usr/local/rush/var directory will have to be cleared again with the above commands.

    That should be all you need to do.

    If you made a mistake, and forgot to clear the /usr/local/rush/var directory, and cloned an entire farm accidentally, then run these cleanup commands with the farm running:

      Forgot To Do Preparation Steps? How To Clean Up
        If you forgot to prepeare the master disk for cloning, you can fix up the farm by running these commands as root: 
        
foreach i ( farm1 farm2 farm3 .. farm99 )
    echo -n Working on ${i}:
    rsh $i /etc/init.d/rush stop 
    rsh $i rm -rf /usr/local/rush/var
    rsh $i mkdir -m 755 /usr/local/rush/var
    rsh $i /usr/local/rush/etc/bin/install.sh
    rsh $i /usr/local/rush/etc/S99rush start
end

        This will clean up a farm that was accidentally cloned with left over files in the /usr/local/rush/var directory.

   Installing www-rush  
    This step is optional.

    If you want to use www-rush, the web interface to rush, make sure *one* of the rush machines is also running a web server (like Apache). You would only need to the following config on the web server.

    1) Copy the www-rush perl script to the webserver's 'cgi-bin' directory.

    
    cp /usr/local/rush/cgi-bin/www-rush /Library/WebServer/CGI-Executables

    2) Install the www-rush documentation in the documentation directory.

    
    cp -rp /usr/local/rush/html/www-rush /Library/WebServer/Documents

    3) Test it by opening Netscape to the URL for the script.

    
    http://yourserver.com/cgi-bin/www-rush
    Make sure your server daemon is running, eg: 
    
    apachectl start

    4) Customize the www-rush script's variables if need be

      Usually the defaults work fine, but sometimes the variables at the top of the www-rush script will need to be modified to help it know about your web server's environment.