Please read INSTALL for general information about installing John on your
system.  Distro maintainers, please also read README-DISTROS for how to
build CPU fallback chains for any x86-64 CPU.

== Preamble

    Important: This document is for a local build in user home directory, not a
    system-wide installation.  In fact, most likely you do not need to install
    John the Ripper system-wide.  Instead, after you compile the source code
    (see below), you may simply enter the "run" directory and invoke John from
    there, e.g. with:

    ./john --list=build-info

    Commands not explicitly prefixed by "sudo" must be run as a regular user
    (the one that will use JtR) rather than as root.

== How to install on Ubuntu (also works on Ubuntu for Windows)

    The steps listed below might also work unchanged on Debian and
    derivatives (untested).

=== Preconditions and Required stuff

    mkdir -p ~/src
    sudo apt-get -y install git build-essential libssl-dev zlib1g-dev

==== Recommended (extra formats and performance)

    sudo apt-get -y install pkg-config libgmp-dev libpcap-dev libbz2-dev

==== If you have NVIDIA GPU(s) (OpenCL support)

    sudo apt-get -y install nvidia-opencl-dev

    The above should be sufficient to build JtR with OpenCL support, but to
    actually use it you also need to install CUDA along with the proprietary
    NVIDIA driver (a suitable revision of which is bundled with CUDA), see:

    https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html

==== If you have AMD GPU(s) (OpenCL support)

    sudo apt-get -y install ocl-icd-opencl-dev opencl-headers

    The above should be sufficient to build JtR with OpenCL support, but to
    actually use it you also need to install one of the proprietary drivers:

    - If you have a recent GPU card and Ubuntu Xenial 16.04 LTS or above,
      the amdgpu-pro graphics stack should be used:

      https://www.amd.com/en/support/kb/release-notes/rn-radpro-lin-16-40#faq-AMD-Product-Compatibility
      https://www.amd.com/en/support/kb/release-notes/AMDGPU-INSTALLATION

    - If you have an older GPU card and Ubuntu up to and including 15.10,
      the old fglrx driver should be used:

      sudo apt-get -y install ocl-icd-opencl-dev opencl-headers fglrx-dev

==== If you (also) want a CPU device for OpenCL (OpenCL support)

    sudo apt-get -y install ocl-icd-opencl-dev opencl-headers pocl-opencl-icd

    We don't recommend using CPUs via OpenCL since JtR is usually far more
    efficient at using them directly, but you do have this weird option.
    Instead of or in addition to POCL, you may (also) install Intel's
    proprietary OpenCL runtime, which is generally more reliable and faster.

==== Optional MPI support

    You probably do not need MPI, it's only for multi-machine clusters with
    shared network storage.  Merely having it compiled in (even if unused)
    may have security and reliability drawbacks.  Most users should read up
    on the "--fork" option instead, which gets compiled in automagically if
    your system supports it.  Having said all this, if you're sure you do
    need MPI support please read README.mpi for instructions.

    Please also note that OpenMP (Open Multi-Processing) is not the same
    as Open MPI (Message Passing Interface).  You do get OpenMP support
    compiled into JtR by default if your system supports it.

==== Optional REXGEN support (experimental; additional "regex" cracking mode)

    NOTE this support is experimental and may not build at all until tweaked.
    The rexgen library is notorious for changing its API between versions,
    breaking stuff.  Leave this step out unless you really know that you want
    it and are capable of fixing issues.  Last known good version is 2.1.5.

    sudo apt-get -y install cmake bison flex
    cd ~/src
    git clone --recursive https://github.com/teeshop/rexgen.git
    cd rexgen
    ./install.sh

    Then add "--enable-rexgen" to ./configure when building john.

=== Clone latest bleeding-edge Jumbo and build

==== Clone the Git repo

    cd ~/src
    git clone https://github.com/openwall/john -b bleeding-jumbo john

==== Build

    cd ~/src/john/src
    ./configure && make -s clean && make -sj4

==== Alternative: OpenMP fallback build

    This effectively makes two builds of JtR, for slight speedup in cases when
    OpenMP is disabled at runtime e.g. when you use "--fork".

    cd ~/src/john/src
    ./configure --disable-openmp && make -s clean && make -sj4
    mv ../run/john ../run/john-non-omp
    ./configure CPPFLAGS='-DOMP_FALLBACK -DOMP_FALLBACK_BINARY="\"john-non-omp\""'
    make -s clean && make -sj4

=== Optionally install TAB-completion

    Please only do this if you intend to use our custom TAB completions in
    bash.  If you don't know what this is, you don't need it.

    sudo make shell-completion

=== Test your build

    cd ~/src/john/run
    ./john --test=0

=== Benchmark your build (this also performs self-tests)

    ./john --test

=== Install all Perl libs required for things like keepass2john.pl

    A few are available as Ubuntu packages:

    sudo apt-get install libcompress-raw-lzma-perl libdigest-md5-perl libimage-exiftool-perl libmime-base64-perl libnet-ldap-perl libnet-pcap-perl

    To get everything needed, you have to install from CPAN:

    sudo apt install cpanminus
    cd ~/src/john/run
    cpanm --installdeps .

=== Install all Python modules required for things like pcap2john.py

    Install most of them as Ubuntu packages (if you like):

    sudo apt-get -y install python-is-python3 python3-pycryptodome python3-scapy python3-parsimonious python3-asn1crypto python3-dpkt python3-cbor2 python3-cryptography python3-simplejson python3-idna python3-lxml python3-ldap3 python3-olefile python3-bsddb3

    Alternatively, use pip3 to install all of them into a virtual environment:

    sudo apt-get install python3 python3-venv python3-pip
    cd ~/src/john/run
    python3 -m venv venv
    . venv/bin/activate
    pip3 install -r requirements.txt
    deactivate

    Later use:

    cd ~/src/john/run
    . venv/bin/activate
     (run tools as needed)
    deactivate