	Installing John the Ripper.

First of all, most likely you do not need to install John the Ripper
system-wide.  Instead, after you extract the distribution archive and
possibly compile the source code (see below), you may simply enter the
"run" directory and invoke John from there.

System-wide installation is also supported, but it is intended for use
by packagers of John for *BSD "ports", Linux distributions, etc., rather
than by end-users.  (If you're in fact preparing a package of John,
please refer to the JOHN_SYSTEMWIDE setting in src/params.h.)

You may have obtained the source code or a "binary" (pre-compiled)
distribution of John the Ripper.  On Unix-like systems, it is typical
to get the source code and compile it into "binary" executables right
on the system you intend to run John on.  On DOS and Windows, however,
it is typical to get a binary distribution which is ready for use.

The following instructions apply to the source code distribution of
John only.  If you have a binary distribution, then there's nothing
for you to compile and you can start using John right away.


	Requirements

The Jumbo versions requires OpenSSL 0.9.7 or later. To get all functionality
you need 1.0.1. For building, not only the run-time libs are needed but also
"devel" stuff like header files. This is often a separate package, so eg.
for Ubuntu you need "libssl-dev" as well as "libssl".

A few helper tools need C++. Some helper tools are written in Python. A couple
helper tools (vncpcap2john and SIPdump) need libpcap. A couple of formats need
extra libraries in order to get included:

	mozilla		libnss
	krb5-18/23	libkrb5
	wowsrp		libgmp (will build without it, but is slower then)

Again, you also need eg. libnss-dev, libkrb5-dev and libgmp-dev in order to
build.


	Compiling the sources on a Unix-like system.

Enter the directory into which you extracted the source code
distribution of John.  Enter the "src" subdirectory.
	cd src

This version of Jumbo has autoconf - that is, it supports the very common
chain of:
	./configure && make

You might want to add "-s" to make, for suppressing normal output and just
print warnings and errors. For a multi-core host you can also add eg. "-j4"
for using 4 cores in parallel when building. This can be written together,
as in:
	./configure && make -sj4

./configure should find and enable any extra stuff you have, including OMP,
OpenCL, CUDA and extra libraries mentioned above. The only exception is MPI
which needs the "--enable-mpi" option to be supplied to configure. If something
is missing, it's likely installed in a non-standard location so you'd need to
pass parameters:
	./configure LDFLAGS=-L/opt/lib CFLAGS="-O2 -I/opt/include" && make

NOTE! If you pass CFLAGS like above, you probably also want to add "-O2"
since it (and "-g") will only be added automatically provided CFLAGS start
out empty. This is a feature of the autoconf macros, not specific to JtR.

You can also disable certain features you don't want, eg:
	./configure --disable-openmp && make

If you have problems with the autoconf feature, you can revert to the
legacy Makefile like this:
	make -f Makefile.orig

You'll get a list of operating systems for which specific support
exists. Note the make target for your system and type:

	make -f Makefile.orig clean SYSTEM

where SYSTEM is the appropriate make target.  Alternatively, if your
system is not listed, use:

	make -f Makefile.orig clean generic

If everything goes well, this will create the executables for John and
its related utilities under "../run/".  You can change directory to
there and start John, like this:

	cd ../run
	./john --test

Alternatively, you may copy the entire "run" directory to anywhere you
like and use John from there.


	A note on moving binaries between systems.

With the "generic" make target, certain machine hardware performance
parameters are detected at compile time.  Additionally, some OS-specific
make targets tell the C compiler to generate and optimize code for the
machine's specific CPU type (this currently applies to C compilers other
than gcc only).  If you then move the binary executable to a different
machine, you might not get the best performance or the program might
not run at all if the CPU lacks features that the C compiler assumed it
would have.  Thus, it is recommended to recompile John on each system if
you use one of these make targets.

Since Linux and *BSD distributions' packages of John typically use make
targets other than "generic" and since they typically use gcc, they are
usually not affected by this potential problem.


	Optimal build on OS X (Jumbo specific)

[This section is not yet updated for "autoconf" as mentioned above. On the
other hand, autoconf is likely to do fine without it]

Using OS X, you can install Xcode (free) and then its "command line tools"
and after that the "macosx-x86-64" target should work fine. However, this
results in suboptimal performance (AVX is not used, and some formats are
disabled due to ancient OpenSSL). Here's how to make the best possible
of your hardware. There are alternatives that probably work fine but these
instructions are for "Homebrew" (http://mxcl.github.io/homebrew/).

  1. Install Homebrew
  2. Install Homebrew's openssl and gcc
  3. From your base "john" directory:
	cp -avi src/osx_as_wrapper.sh /usr/local/bin/as
  4. Link whatever gcc version you got from Homebrew to just "gcc" in the
     /usr/local/bin directory. This example is for gcc-4.7:
        ln -s gcc-4.7 /usr/local/bin/gcc
  5. Make sure /usr/local/bin preceeds /usr/bin in your $PATH

After the above, you should be able to build "macosx-x86-64-native" which
may use AVX and/or whatever extra features your CPU has got.

UPDATE: It seems OS X 10.9 Mavericks (and on, hopefully) can build the
-native target without any external tools or tricks. However, the above
instructions (using a real gcc as opposed to Apple's llvm-based one) may
still result in a slightly better performing build.


	OpenSSL on OS X

The native OpenSSL in OSX is older than your mother. Install a newer one
like this (Homebrew example):

  $ brew install openssl
  $ ln -s /usr/local/opt/openssl /usr/local/ssl


	CUDA on OS X

Download CUDA from Nvidia and install it. If build errors out complaining
about llvm-gcc not found, try this (Homebrew example):

  $ brew install llvm-gcc-28
  $ sudo \
      ln -s /usr/local/Cellar/llvm-gcc28/2.8/bin/llvm-gcc /usr/bin/llvm-gcc-4.2

After that you should be able to build with the default Makefile.
