Rush Logo Rush Mac Install Instructions
V 103.07b 05/21/16
(C) Copyright 2008, 2016 Seriss Corporation. All rights reserved.
(C) Copyright 1995,2000 Greg Ercolano. All rights reserved.

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 the machine's hostname is set correctly

    Use either scutil, or on older Macs use a HOSTNAME=xxx entry in the /etc/hostconfig file.

    You want to avoid the 'hostname.local' rendezvous/Bonjour stuff that causes hostname instability (the hostname changes randomly). Setting the hostname in System Preferences > Sharing isn't sufficient; you'll still see the hostname(1) command show inconsistent names like "Fred's Mac" or end in ".local", which is bad.

      Current OSX Releases (OSX 10.8/Mountain Lion, and up)
        In Mountain Lion and up, use the scutil command.
        So if the machine should be called 'tahoe', run this as root:

          scutil --set HostName      "tahoe"
          scutil --set LocalHostName "tahoe"
          scutil --set ComputerName  "tahoe"

        It's best to set all three values to the same name.

        Hostnames can /only/ contain combos of alphanumeric characters and dashes,
        nothing else. Don't use spaces, underbars, etc. Leave off the domain name
        extension; the right place for the domain name is in the "Search Name".

        After making your changes, reboot.

      Older OSX Releases (OSX 10.7/Lion, and Older)
        On older versions of OSX, add a HOSTNAME=xxx entry in the /etc/hostconfig file instead.
        So for a host called "tahoe", use:

          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 include dashes around the hostname.

        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.

        After making your changes, reboot.

  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
    sudo tar xvfzp /tmp/rush-xxxxx.tar.gz

    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 you're reading for setting up the first machine, then you can use the Network Install instructions to set up the rest of the network easily by just copying the /usr/local/rush directory to the other machines.

    • 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 directory completely on an NFS drive.
      Install it in a local directory on each machine. Here is why.

      For cloud configurations, you may want to install Rush on an NFS server. But you'll need to make sure at least the rush/var directory is local. This is because rush read/writes host-specific files to this directory, and assumes the var dir is unique to each machine. So it must be local. All the other rush/* subdirs could be symlinks to the server.

  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.

      /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:

    • connection refused

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

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

    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 configuration settings

    • Pathname Translations

      If you need them, set up "path_convert" commands in the rush/etc/path_convert file
      to configure pathnames in a from/to format. For instance,
      converting Windows "Z:/share" paths to cross platform "//ourserver/share" paths.

    • Automatic Drive Mappings (Windows)

      If you need them, set up "drive_map" commands in the rush/etc/path_convert file
      to configure drive letter mappings. For instance,
      mapping "Z:" to "//ourserver/share".

    • Cpu Accounting

      By default, Rush maintains a history of cpu utilization information in the /usr/local/rush/var/cpu.acct file, which is local to each render node. 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

      If, however, you want to keep the cpu accounting data, you can centralize the data to a file server using the new rush.conf command cpuacct.dbasedir. This tells the rush daemons to regularly write the cpu accounting data to a file server, and rush will regularly update the file info into a date stamped directory to make it easy to get at the data.

  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.