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 Fedora

    The steps listed below might also work unchanged on RHEL 8 and
    derivatives such as CentOS 8 (untested).  For RHEL 7 / CentOS 7
    and earlier, use "yum" in place of "dnf".

    If anything below fails, run "sudo dnf update" and try again.

=== Preconditions and Required stuff

    sudo dnf update
    sudo dnf install git make gcc openssl-devel

==== Recommended (extra formats and performance)

    sudo dnf install gmp-devel libpcap-devel bzip2-devel

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

=== Clone latest bleeding-edge Jumbo and build

==== Clone the Git repo

    mkdir -p ~/src
    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

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

    cd ~/src/john/run
    cpanm --installdeps .

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

    Use pip3 to install all of them into a virtual environment:

    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
