Rush Logo Rush Mac Install Instructions
(C) Copyright 1995,2000 Greg Ercolano. All rights reserved.
V 102.42b-prerelease 08/19/09

Mac OSX Install Instructions




   Installing Rush  
  1. Be sure your network meets these prerequisite requirements.

    This is essential to ensure a stable network so Rush can operate reliably.
    It's important machine's hostnames and IP addresses don't change after casual reboots. IP addresses should be consistent through reboots, which a well configured static DNS (or /etc/hosts) configuration provides.

  2. Make sure your /etc/hostconfig file has a "HOSTNAME=your_hostname" entry

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

    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. Do NOT put dashes around the hostname.

    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.

  3. Extract the rush tar file.

    Extract the tar file to /usr/local/rush.
    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 -

    Some notes on extraction:

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

    • If /usr/local doesn't exist, create it first: 
      		mkdir -m 755 /usr/local
		chown 0:0 /usr/local

    • To install Rush on a large network..
      First complete all these install steps for setting up the first machine, then you can use the Network Install instructions to set up the rest of the network easily.

    • Installing rush in locations other than /usr/local/rush is not recommended.
      But if you /really/ must, refer to these instructions.

    • Do *not* install the rush binaries or config files on an NFS drive.
      Keep them all in a local directory on each machine. Here is why.

  4. Configure the /usr/local/rush/etc/hosts file.

    It should contain the hostnames of all machines that will be rendering or submitting jobs, in addition to the license server. See Hosts File for a description of this file's format.

  5. Install the license that was emailed to you as /usr/local/rush/etc/license.dat

  6. 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:

        Firewall Disable
        10.4 and older
        (Tiger and older)
        		System Preferences > Sharing > Firewall > Stop
        10.5 and newer
        (Leopard, Snow Leopard..)
        		System Preferences > Security > Firewall > Stop

      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.

  7. Run the install script.

    Run the install script by typing: 

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

    Watch for any error messages in the output.

  8. 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 invoke '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

    Some errors that may occur:

    • can't open port lock file '/usr/local/rush/var/nextport': Permission denied

      You either weren't running as root when you ran the install script, or somehow skipped running the install script. To fix this, be sure you are logged in as root, and re-run the install script.

    • connection refused

      This means the daemon wasn't able to start.
      Look in the /usr/local/rush/var/rushd.log for error messages.

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

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

  9. Install the submit scripts for the users

    If you haven't already installed the scripts on your server yet, follow these instructions for installing the submit scripts on your file server: 'Making Scripts Available To Users'.

    Once installed, users can make desktop shortcuts to the scripts by using these instructions: 'Making Desktop Shortcuts To Submit Scripts'

    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.

  10. (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.

  11. That's it.

    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 
      
    for i in host1 host2 host3 .. ; do
	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
    done

    Now verify all the daemons have started. 

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

    Make sure any Software Firewalls are disabled (or are at least configured to allow rush to communicate), as firewall software can prevent Rush from being able to communicate.

   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:
        
    /usr/local/rush/etc/S99rush 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: 
        
for i in farm1 farm2 farm3 .. farm99 ; do
    echo -n Working on ${i}:
    rsh $i /usr/local/rush/etc/S99rush 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
done

        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 Safari 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.