INSTALLING

== Building ==

=== Requirements ===

 * Autoconf
 * Automake
 * Libtool
 * OpenSSL development package or libgcrypt development package.
 * Airmon-ng (Linux) requires ethtool.
 * On windows, cygwin has to be used and it also requires w32api package.
 * Linux: LibNetlink 1 or 3. It can be disabled by setting the flag 'libnl' to false.
 * pkg-config (pkgconf on FreeBSD)
 * FreeBSD, OpenBSD, NetBSD, Solaris and OS X with macports: gmake
 * Linux/Cygwin: make and Standard C++ Library development package (Debian: libstdc++-dev)

=== Optional stuff ===

 * If you want SSID filtering with regular expression in airodump-ng
   (-essid-regex) pcre development package is required.
 * If you want to use airolib-ng and '-r' option in aircrack-ng,
   SQLite development package >= 3.3.17 (3.6.X version or better is recommended)
 * If you want to use Airpcap, the 'developer' directory from the CD is required.
 * For best performance on FreeBSD (50-70% more), install gcc5 via: pkg install gcc5
          Then compile with: gmake CC=gcc5 CXX=g++5
 * rfkill

=== Resolving the basic requirements ===

Below are instructions for installing the basic requirements to build
`aircrack-ng` for a number of operating systems.

==== Cygwin (Windows) ====

Cygwin requires the full path to the `setup.exe` utility, in order to
automate the installation of the necessary packages. In addition, it
requires the location of your installation, a path to the cached
packages download location, and a mirror URL.

An example of automatically installing all the required dependencies
is as follows:

    `c:\cygwin\setup-x86.exe -qnNdO -R C:/cygwin -s http://cygwin.mirror.constant.com -l C:/cygwin/var/cache/setup -P autoconf -P automake -P bison -P gcc-core -P gcc-g++ -P mingw-runtime -P mingw-binutils -P mingw-gcc-core -P mingw-gcc-g++ -P mingw-pthreads -P mingw-w32api -P libtool -P make -P python -P gettext-devel -P gettext -P intltool -P libiconv -P pkg-config -P git -P wget -P curl -P libpcre-devel -P openssl-devel -P libsqlite3-devel`

==== Debian/Ubuntu ====

    `sudo apt install build-essential autoconf automake libtool pkg-config libnl-3-dev libssl-dev libpcre3-dev`

==== FreeBSD using PKG ====

    `pkg install autoconf automake libtool pkgconf sqlite3 git python3`

==== MSYS2 (Windows) ====

    `pacman -Sy autoconf automake1.15 libtool msys2-w32api-headers msys2-w32api-runtime pkg-config git python openssl-devel openssl libopenssl msys2-runtime-devel gcc binutils make pcre-devel libsqlite-devel`

=== Compiling ===

To build `aircrack-ng`, the Autotools build system is utilized. Autotools replaces
the older method of compilation.

NOTE: If utilizing a developer version, eg: one checked out from source control,
you will need to run a pre-`configure` script. The script to use is one of the
following: `autoreconf -i` or `env NOCONFIGURE=1 ./autogen.sh`.

First, `./configure` the project for building with the appropriate options specified
for your environment:

    `./configure <options>`

TIP: If the above fails, please see above about developer source control versions.

Next, compile the project (respecting if `make` or `gmake` is needed):

 * Compilation:

    `make`

 * Compilation on *BSD or Solaris:

    `gmake`

Finally, the additional targets listed below may be of use in your environment:

 * Execute all unit testing:

    `make check`

 * Strip debugging symbols:

    `make strip`

 * Installing:

    `make install`

 * Uninstall:

    `make uninstall`


====  `./configure` flags ====

When configuring, the following flags can be used and combined to adjust the suite
to your choosing:

* with-airpcap=DIR:  needed for supporting airpcap devices on windows (cygwin or msys2 only)
                Replace DIR above with the absolute location to the root of the
                extracted source code from the Airpcap CD or downloaded SDK available
                online.

* with-experimental: needed to compile `tkiptun-ng`, `easside-ng` (and `buddy-ng`) and
                    `wesside-ng`. Building besside-ng-crawler requires LibPCAP 
                    (development package). On debian based distro, install libpcap-dev

* with-ext-scripts: needed to build `airoscript-ng`, `versuck-ng`, `airgraph-ng` and 
                   `airdrop-ng`. 
                   Note: Experimental. Each script has its own dependences.
                   Note: It's only required in install phase.

* with-gcrypt:   Use libgcrypt crypto library instead of the default OpenSSL.
                And also use internal fast sha1 implementation (borrowed from GIT)
                Dependency (Debian): libgcrypt20-dev

* with-duma:	Compile with DUMA support. DUMA is a library to detect buffer overruns and under-runs.
            	Dependencies (debian): duma

* with-xcode:    Set this flag to true to compile on OS X with Xcode 7+.

===== Examples =====

  * Configure and compiling:

    `./configure --with-experimental`
    `make`

  * Compiling wth gcrypt:

    `./configure --with-gcrypt`
    `make`

  * Installing:

    `make install`

  * Installing, with external scripts:

    `./configure --with-experimental --with-ext-scripts`
    `make`
    `make install`

  * Testing (with sqlite, experimental and pcre)

    `./configure --with-experimental`
    `make`
    `make check`

  * Compiling on OS X with macports (and all options):

    `./configure --with-experimental`
    `gmake`

  * Compiling on OS X 10.10 with XCode 7.1 and Homebrew:

    `env CC=gcc-4.9 CXX=g++-4.9 ./configure`
    `make`
    `make check`

    *NOTE*: Older XCode ships with a version of LLVM that does not support CPU feature
    detection; which causes the `./configure` to fail. To work around this older LLVM,
    it is required that a different compile suite is used, such as GCC or a newer LLVM
    from Homebrew.

    If you wish to use OpenSSL from Homebrew, you may need to specify the location
    to its' installation. To figure out where OpenSSL lives, run:

    `brew --prefix openssl`

    Use the output above as the DIR for `--with-openssl=DIR` in the `./configure` line:

    `env CC=gcc-4.9 CXX=g++-4.9 ./configure --with-openssl=DIR`
    `make`
    `make check`

  * Compiling on FreeBSD with better performance

    `env CC=gcc5 CXX=g++5 ./configure`
    `gmake`

== Packaging ==

Automatic detection of CPU optimization is done at run time. This behavior
**is** desirable when packaging Aircrack-ng (for a Linux or other distribution.)

Also, in some cases it may be desired to provide your own flags completely and
not having the suite auto-detect a number of optimizations. To do this, add
the additional flag `--without-opt` to the `./configure` line:

`./configure --without-opt`

== Run-time location of SIMD binaries ==

Typically, the full path that is compiled in to the `aircrack-ng` binary is
`/usr/libexec/aircrack-ng`. However, during development and/or packaging, it
may be of use to specify a path that is dynamic in nature.

The environment variable `AIRCRACK_LIBEXEC_PATH` may be used to specify the
location of the SIMD-optimized binaries. An example of such use is as
follows:

`env AIRCRACK_LIBEXEC_PATH=/home/user/dev/aircrack-ng/src ./src/aircrack-ng`

== Using precompiled binaries ==

=== Linux/BSD ===

* Use your package manager to download aircrack-ng
* In most cases, they have an old version.

=== Windows ===

 * Install the appropriate "monitor" driver for your card (standard drivers doesn't work for capturing data).
 * aircrack-ng suite is command line tools. So, you have to open a commandline
   `Start menu -> Run... -> cmd.exe` then use them
 * Run the executables without any parameters to have help

== Documentation ==

Documentation, tutorials, ... can be found on https://www.aircrack-ng.org

See also manpages and the forum.