vi:sw=4:ts=4:ai:sm:et:wm=10 ====================================================================== Introduction The documentation for McFeely is a bit spread out and confusing. This document attempts to alleviate some of the confusion by providing a step by step guide to installing (from RPM) and then running a mcfeely server and client installation. If you have any questions about this, please subscribe to the mcfeely-l@systhug.com mailing list by sending mail to mcfeely-l-subscribe@systhug.com. In fact, if you poke at McFeely at all please subscribe to the list so we can chat. It's lonely. This information is clearly rough and in need of improvement, if you have some suggestions for improvement please get on the mailing list and let us know. Thanks. ====================================================================== Installation To install you will need the following rpms: mcfeely-client mcfeely-server mcfeely-common knetstring You should be able to find all of these in the mcfeely distribution directory at http://web.systhug.com/mcfeely/dist/ knetstring provides the shared library used by the client and server to talk with one another in a reliable fashion. You will also need to have a version of the perl IO module which supports the blocking() method. IO 1.20 works and is available from CPAN. Before you install the rpms, create the user and groups which McFeely needs to run. YOU MAKE THESE SORTS OF CHANGES AT YOUR OWN RISK. MAKE SURE YOU KNOW WHAT YOU ARE DOING! - create a mcfeely user with a home of /opt/mcfeely and /bin/bash as its shell - create a mcfeely group, this is the group the server runs as - create a mcqueue group. To this group add users who you wish to allow to enqueue mcfeely jobs. You don't want to do this all will nilly, think before you act. We suggest that you don't add anyone to this group until after you have completed your testing and are familiar with the system. ALSO: because of some weirdness with installing perl modules from RPMS on different versions of Redhat you may find that you need to do the following to make the perl modules that McFeely will install visible to your system: cd /usr/lib/perl5/site_perl cp -a 5.005/* . rm -r 5.005 ln -s . 5.005 Once you have done that, install the RPMS. Next, mcfeely needs to be configured so it knows where your clients are and how to authenticate them. In /opt/mcfeely/control create a file called 'hosts' that is owned by root and is 644. In there put the information about the mcfeely clients. saliva.kiva.net saliva 757 206.97.64.58 The files are client identifier (the fully expanded hostname of the client), the host to communicate with, the port on that host to comunicate on, and the identifier of the secret file. By convention, the secret-file is the IP of the client. The second and third fields allow you to use ssh tunnels if you like. This is not required, and if you don't understand ssh tunnels you may want to ask on the mailing list about how to do this. But if you want to do it see the ssh instructions at the end of this document. Next, we need to create a secret that is to be shared between the client and the server. A program, /opt/mcfeely/bin/secretmaker, will create a file called newsecret in the current directory. Copy that to /opt/mcfeely/control/mysecret and /opt/mcfeely/control/secrets/. Using the example above the secret-file-name would be 206.97.64.58. Use what works for your configuration. These files should be owned by root and group mcfeely, mode 640. Now the mcfeely server and client process need to be run. The mcfeely server is a continuously running processes so should therefore start at boot time and run continuously from there. An initscript is provided '/etc/rc.d/init.d/mcfeely' which may be used to start the server process. The script provides for syslogging to /var/log/mcfeely/mcfeely.log via syslog facility local6. If you do not which to use the initscript you may simply do: /opt/mcfeely/bin/mcfeely-start For the client side you need to run mcfeely-ttpd. mcfeely-ttpd needs a friend to help it listen on port 757. The rpms make the necessary additions to the /etc/services and /etc/inetd.conf files. /etc/services: ttp2 757/tcp # mcfeely task transfer /etc/inetd.conf: ttp2 stream tcp nowait.1000 root /opt/mcfeely/bin/mcfeely-ttpd mcfeely-ttpd The 'nowait.1000' is because the default limit of only 40 connections per minute is too low on a busy mcfeely client. If you wish you can use a tool like tcpserver from Dan Bernstein (of qmail fame, see www.qmail.org) instead of inetd: /usr/local/bin/tcpserver -v -c8 -u0 -g0 saliva.kiva.net 757 \ /opt/mcfeely/bin/mcfeely-ttpd & mcfeely-ttpd will syslog to the LOG_DAEMON facility, which on most redhat installation will put the output into /var/log/messages. If your mcfeely client is on another machine you must adjust the control/hosts file to include the information about the other host. You may have as many mcfeely clients as you like. ====================================================================== Testing If you are not using tcpserver you can skip this step, but make sure inetd is configured and 'tail /var/log/messages|grep mcfeely' to get relevant log output. In one window start up mcfeely-ttpd (the client) with tcpserver (do this as root): /usr/local/bin/tcpserver -c8 -v -g 0 -u 0 scalding.bton.kiva.net 757 \ /opt/mcfeely/bin/mcfeely-ttpd replacing the hostname with your hostname. In a window start up mcfeely (the server) by running this command (as root): /etc/rc.d/init.d/mcfeely start and tail -f /var/log/mcfeely/mcfeely.log In another window run: /opt/mcfeely/bin/hostcheck.pl Give your mcfeely client's name as the host and test_comm as the comm: [root@cold /root]# /opt/mcfeely/bin/hostcheck.pl Hostname? [] scalding Comm? [] test_comm Args? [] 1 If everything is working you should recieve a mail message to 'root' stating success. The mcfeely-start window will include some logging information, as will the mcfeely-ttpd window. If that works you can then use the serverslam.pl program to _aggressively_ test your mcfeely setup. serverslam.pl can be used to inject large numbers of jobs with random numbers of tasks to a given client. For example: ./serverslamp.pl saliva test_comm 5 5 will inject 5 jobs of up to 5 tasks a piece (each running test_comm) to the mcfeely client on saliva. This has been used to inject well over 5000 concurrent tasks. A 5th and 6th argument let you choose to set the fnot and snot (see the McFeely::Job perl documentation) flags if you so choose. ====================================================================== Using SSH: It is possible to set up ssh tunnels between the mcfeely server and the mcfeely clients. This encrypts the transaction providing increased security. For example if 'server' is your mcfeely server and saliva is your mcfeely client you can create an ssh tunnel from saliva to server, say on port 45678. Then your /opt/mcfeely/control/hosts file would look like this: saliva.kiva.net server 45678 206.97.64.58 On the saliva end of things ssh tunnels would need to be created. A program called 'snooze' is included in /opt/mcfeely/bin to help with this. Snooze does nothing, it just sleeps. Every now and again it wakes up to check for the presence of it's parent (ssh). If it is not there, it dies. The mcfeely user on the client side must create a key with no passphrase and put the identity.pub in /opt/mcfeely/.ssh/authorized_keys on the server. All owned as the mcfeely user. On the client side create (as user mcfeely) a tunnel: ssh -a -n -x -R 45678:saliva:757 server /opt/mcfeely/bin/snooze & Or something along those lines. Now, when the server side of mcfeely tries to talk to saliva:757, it will actually talk to server:45678 but get through to saliva:757 over the encrypted ssh connection. If you want these tunnels to be permanent you can set them up with supervise (see http://www.qmail.org/) in initscripts or running them out of init may work as well.