			RSA-129 Information
			   Derek Atkins
			 <warlord@MIT.EDU>
			    26 Oct 1993

Version: $Id: README,v 1.5 1993/10/26 21:54:57 warlord Exp $

	INTRODUCTION
	------------

	This document describes how to get started on the RSA-129
project using MPQS, the Multiple Polynomial Quadratic Sieve.  This
describes how to build the software and set up your machines to start
running the sieve and sending results back to the central location.
This document assumes that you understand what we are doing and why,
and where the prize money will go if we win it.

	If you are reading this, then you have successfully obtained a
copy of the mpqs sources.  Included in this distribution you should
see the following files: IN, Makefile, lip.c, lip.h, mpqs.c,
sparc-solaris.s, and sparc-sunos.s.

	GETTING STARTED
	---------------

	First thing to do is to compile the siever, called mpqs.
Currently this software builds on a number of UNIX platforms, and each
has a make rule to go with the machine type:

	Make Rule	Machine
	---------	-------
	DS_mpqs		DECstations (ultrix)
	S4a_mpqs	Sun4 (SunOS4)
	S4S_mpqs	Sun4 (Solaris)
	VS_mpqs		VAXstation (bsd43)
	alpha_mpqs	DEC alpha (osf/1)
	HP_mpqs		HP/UX (requires unbundled compiler)
	HP_gcc_mpqs	HP/UX with gcc compiler
	rs6000_mpqs	RS/6000 (AIX)
	SGI1_mpqs	r2000/r3000 CPU
	SGI2_mpqs	r4000 CPU
	linux_mpqs	i86/Linux
	Gen_mpqs	(A good starting point)

	You should now have a file called "mpqs" in the current build
directory.  This should be moved to some place where all the worker
machines can get to it, such as an NFS or AFS volume, or copy it to
each machine.  If this destination is a shared directory, you can set
the INSTALLDIR variable in the makefile and then "make install" to
copy the program.

	All worker machines need to have access to the file "RESTART".
This will get created the first time you run mpqs, and each subsequent
run can use this file.  The RESTART file will be just short of 5 Meg,
so be prepared for this to be created.  (See the section on creating
the RESTART file for more information).  Each worker machine can use
the same RESTART file.  If this is on a NFS or AFS filesystem, each
worker need not generate this file, which saves a lot of time and disk
space.

	Enclosed in this package is a file called "IN". This is what
you need to feed to a worker to start sieving.  On the first line of
this file there is a letter `i', which needs to be replaced with the
UID you have assigned to this particular mpqs process.  UIDs are
described in more detail later in this document.  For example, if you
are running on 100 machines and have the UID range of 1000-1099, then
start the first worker at 1000.  An example of the "IN" file for this
worker is:

2 1 1000      <- this is the UID assigned
114381625757888867669235779976146612010218296721242362562561842935706\
935245733897830597123563958705058989075147599290026879543541
5 524338 163336000 108 1073741824
10174969370491404933477808051
1
factor@hot-spare.mit.edu

	The last line, "factor@hot-spare.mit.edu" is the mailing
address where factorization data is sent.  Only data created by the
mpqs process should be sent to this address.  Also, this address
should not be changed without consulting the leaders of the RSA-129
project.

	Note: It is possible, if you cannot send mail directly, to
collect mail on this siever and then send it in at a later date.  If
you change the "1" in the second-to-last line to a "0", it will cause
mpqs to not attempt to send in relations via mail.  Rather, mpqs will
save the relations to a file, which you must mail in by hand at a
later date.

	A good way to do this is to copy the IN file into /usr/tmp on
each machine you set up as an mpqs client, and on each machine edit
the file in /usr/tmp to reflect the UID of that particular run.  If
you have RESTART and the mpqs program in some distributed file system,
this works well.  As an example, what I do is copy the IN file to
/usr/tmp, edit the file in /usr/tmp to reflect the UID of the process,
and then run the mpqs process (more on running the process later).

	RUNNING MPQS
	------------

	To run mpqs, the easiest way is to cd into some temporary
directory, like /usr/tmp, and then run the program:

   mpqs /path/to/RESTART < /path/to/IN > log.mpqs

	The first argument to mpqs is the path to the RESTART file.
(This does NOT need to be an explicit path; it can be a path from the
current directory.) Then you pipe the IN file into stdin of the
program, and shove the output into a log file, called "log.mpqs".  It
is possible to have any of these files in the current working
directory.  Also, the current working directory is where mpqs will
place its temporary output files to collect the relation data before
sending it via mail to the collecting site.

	The mpqs process wants to grab as much CPU time as possible.
Therefore, you might want to "nice" the process to allow other
programs to run.  In so doing, you do not really reduce the amount of
computation being done, but you allow others to use the system in some
manner.  You can nice the process at startup by running this command
instead of the one given above:

   nice +19 mpqs /path/to/RESTART < /path/to/IN > log.mpqs

	If the RESTART file you give is either non-existant or empty,
mpqs will first create the RESTART file, store it in the designated
file, and then continue processing.

	GENERATING RESTART
	------------------

	Generating RESTART is fairly simple and follows the similar
lines to just starting mpqs.  Actually, the first time you run mpqs,
it will automatically generate the RESTART file for you.  So, to
generate the RESTART file, first cd into a temporary directory, and
then run mpqs as above.

	After the RESTART file is created, the mpqs process will
continue to run as if it had found a RESTART file.

	OBTAINING UIDS
	--------------

	Before you can start processing data for the RSA-129 project,
you need to obtain a set of UIDs to use.  *EACH* mpqs process needs to
run with a different UID.  If an mpqs process gets killed for some
reason and you want to restart it, you should give it a new UID
number, or it will spend all its starting time recreating the data
that had been created on the last run of the program.

	There is a mail server set up to process your UID requests.
To request a UID, send mail to "factorid@hot-spare.mit.edu".  In the
message to factorid, put the following two lines in the body of the
message:

path# your-email-address
id# number-of-ids-you-want

	Note: The strings "path#" and "id#" are *required* to be
there, as the response software keys off those phrases.

	When you send this, it should respond with that appropriate
number of UIDs which you can now be sure are unique to the RSA-129
project.  This assures that no one will duplicate any efforts.


	MAILING LISTS
	-------------

	There is a mailing list for all the RSA129 workers.  If you
want to be on this list, please send mail to:
	rsa129-request@iastate.edu 
 and ask to be put on the worker list.  This list receives notices
about software updates, and statistics about the progress of the
project.  All workers are highly recommended to be on this list, and
non workers can also be added at their request.

	NOTES
	-----

	Be sure to use a different UID *every time* you start mpqs.
If you allow a machine to factor for a while, then restart it using
the same UID, it will generate the same output.  If you use a
different UID, then overlap is minimized and more useful data will be
returned.  

	This UID is an MPQS Universal IDentifier, and has no relation
to UNIX UID or any other IDs you may think of.  The mpqs process may
be run as any user on each machine, but the UID for the mpqs process,
which you obtain from factorid@hot-spare.mit.edu, must be unique!  In
actuality, the MPQS UID is a seed into a random number generator.  If
two mpqs processes are running with the same UID, then they will
generate the same random numbers, and hence both processes will cover
the same space.  We do not want this to happen, which is why we say
that each mpqs process should have its own UID.

	The mpqs process, as it is built my this Makefile, will take
approximately 12 Meg of core space.  If it needs to swap at all, it
will really hose the machine.  You can reduce the core size by
reducing the MAXSIEVE value from 3000000 to some value no lower than
100000.  This should reduce it to about 8-9 Meg of core space.  If
this is still not small enough for your memory, you might also want to
build the program "-DNO_SQRTKN".  This will cause mpqs to NOT keep a
copy of the RESTART file in core, which has two effects.  First, it
will reduce the amount of core by about 2 more Meg.  Second, it will
cause mpqs to reread the file from disk, which requires it to
be present all the time!  These tradeoffs are not recommended unless
absolutely necessary.  Send mail to the RSA-129 Project Administrators
for help with this.

	Any questions, please mail to rsa129-info@iastate.edu, and it
will be answered as quickly as possible.

	Thank you for joining the RSA-129 project.

-RSA129 Project Coordinators
