Debian Codegraph @

INSTALLING

raw
1 == Building ==
2
3 === Requirements ===
4
5 * Autoconf
6 * Automake
7 * Libtool
8 * shtool
9 * OpenSSL development package or libgcrypt development package.
10 * Airmon-ng (Linux) requires ethtool, usbutils, and often pciutils.
11 * On Windows, cygwin has to be used and it also requires w32api package.
12 * On Windows, if using clang, libiconv and libiconv-devel
13 * Linux: LibNetlink 1 or 3. It can be disabled by passing --disable-libnl to configure.
14 * pkg-config (pkgconf on FreeBSD, DragonFlyBSD, OpenBSD and NetBSD)
15 * FreeBSD, DragonFlyBSD, OpenBSD, NetBSD, Solaris and OS X with Macports: gmake
16 * Linux/Cygwin: make and Standard C++ Library development package (Debian: libstdc++-dev)
17
18 Note: Airmon-ng only requires pciutils if the system has a PCI/PCIe bus and it is populated.
19 Such bus can be present even if not physically visible. For example, it is present,
20 and populated on the Raspberry Pi 4, therefore pciutils is required on that device.
21
22 === Optional stuff ===
23
24 * If you want SSID filtering with regular expression in airodump-ng
25 (--essid-regex) PCRE or PCRE2 development package is required.
26 * If you want to use airolib-ng and '-r' option in aircrack-ng,
27 SQLite development package >= 3.3.17 (3.6.X version or better is recommended)
28 * If you want to use Airpcap, the 'developer' directory from the CD/ISO/SDK is required.
29 * In order to build besside-ng, besside-ng-crawler, easside-ng, tkiptun-ng and wesside-ng,
30 libpcap development package is required (on Cygwin, use the Airpcap SDK instead; see above)
31 * rfkill
32 * If you want Airodump-ng to log GPS coordinates, gpsd is needed
33 * For best performance on SMP machines, ensure the hwloc library and headers are installed. It is strongly recommended on high core count systems, it may give a serious speed boost
34 * CMocka for unit testing
35 * For integration testing on Linux only: tcpdump, HostAPd, WPA Supplicant and screen
36
37 === Installing required and optional dependencies ===
38
39 Below are instructions for installing the basic requirements to build
40 `aircrack-ng` for a number of operating systems.
41
42 Note: CMocka, tcpdump, screen, HostAPd and WPA Supplicant should not be dependencies when packaging Aircrack-ng.
43
44 ==== Linux ====
45
46 ===== Arch Linux =====
47
48 `sudo pacman -Sy base-devel libnl openssl ethtool util-linux zlib libpcap sqlite pcre2 hwloc cmocka hostapd wpa_supplicant tcpdump screen iw usbutils pciutils`
49
50 ===== Debian/Ubuntu =====
51
52 `sudo apt-get install build-essential autoconf automake libtool pkg-config libnl-3-dev libnl-genl-3-dev libssl-dev ethtool shtool rfkill zlib1g-dev libpcap-dev libsqlite3-dev libpcre2-dev libhwloc-dev libcmocka-dev hostapd wpasupplicant tcpdump screen iw usbutils`
53
54 ==== Fedora ====
55
56 `sudo yum install libtool pkgconfig sqlite-devel autoconf automake openssl-devel libpcap-devel pcre2-devel rfkill libnl3-devel gcc gcc-c++ ethtool hwloc-devel libcmocka-devel make file expect hostapd wpa_supplicant iw usbutils tcpdump screen zlib-devel`
57
58 ==== CentOS/RHEL 7 ====
59
60 `sudo yum install epel-release`
61 `sudo ./centos_autotools.sh`
62 # Remove older installation of automake/autoconf
63 `sudo yum remove autoconf automake`
64 `sudo yum install sqlite-devel openssl-devel libpcap-devel pcre2-devel rfkill libnl3-devel ethtool hwloc-devel libcmocka-devel make file expect hostapd wpa_supplicant iw usbutils tcpdump screen zlib-devel`
65
66 Note: autoconf, automake, libtool, and pkgconfig in the repositories are too old. The script centos_autotools.sh automatically installs dependencies to compile then install the tools.
67
68 ==== CentOS/RHEL 8 ====
69
70 `sudo yum config-manager --set-enabled powertools`
71 `sudo yum install epel-release`
72 `sudo yum install git libtool pkgconfig sqlite-devel autoconf automake openssl-devel libpcap-devel pcre2-devel rfkill libnl3-devel gcc gcc-c++ ethtool hwloc-devel libcmocka-devel make file expect hostapd wpa_supplicant iw usbutils tcpdump screen zlib-devel`
73
74 ===== openSUSE =====
75
76 `sudo zypper install autoconf automake libtool pkg-config libnl3-devel libopenssl-1_1-devel zlib-devel libpcap-devel sqlite3-devel pcre2-devel hwloc-devel libcmocka-devel hostapd wpa_supplicant tcpdump screen iw gcc-c++ gcc ethtool pciutils usbutils`
77
78 ===== Mageia =====
79
80 `sudo urpmi autoconf automake libtool pkgconfig libnl3-devel libopenssl-devel zlib-devel libpcap-devel sqlite3-devel pcre2-devel hwloc-devel libcmocka-devel hostapd wpa_supplicant tcpdump screen iw gcc-c++ gcc make`
81
82 ===== Alpine =====
83
84 `sudo apk add gcc g++ make autoconf automake libtool libnl3-dev openssl-dev ethtool libpcap-dev cmocka-dev hostapd wpa_supplicant tcpdump screen iw pkgconf util-linux sqlite-dev pcre2-dev linux-headers zlib-dev pciutils usbutils`
85
86 Note: Community repository needs to be enabled for iw
87
88 ==== Clear Linux ====
89
90 `sudo swupd bundle-add c-basic devpkg-openssl devpkg-libnl devpkg-hwloc devpkg-libpcap devpkg-pcre2 devpkg-sqlite-autoconf ethtool wget network-basic software-testing sysadmin-basic wpa_supplicant`
91
92 Note: hostapd must be compiled manually, it is not present in the repository
93
94 ==== BSD ====
95
96 ===== FreeBSD =====
97
98 `pkg install pkgconf shtool libtool gcc9 automake autoconf pcre2 sqlite3 openssl gmake hwloc cmocka`
99
100 ===== DragonflyBSD =====
101
102 `pkg install pkgconf shtool libtool gcc8 automake autoconf pcre2 sqlite3 libgcrypt gmake cmocka`
103
104 ===== OpenBSD =====
105
106 `pkg_add pkgconf shtool libtool gcc automake autoconf pcre2 sqlite3 openssl gmake cmocka`
107
108 ===== NetBSD =====
109
110 `pkg_add pkgconf libtool gcc7 automake autoconf pcre2 sqlite3 openssl gmake cmocka`
111
112 ==== macOS ====
113
114 XCode, Xcode command line tools and HomeBrew are required.
115
116 `brew install autoconf automake libtool openssl shtool pkg-config hwloc pcre2 sqlite3 libpcap cmocka`
117
118 ==== Windows ====
119
120 ===== Cygwin =====
121
122 Cygwin requires the full path to the `setup.exe` utility, in order to
123 automate the installation of the necessary packages. In addition, it
124 requires the location of your installation, a path to the cached
125 packages download location, and a mirror URL.
126
127 An example of automatically installing all the dependencies
128 is as follows:
129
130 `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 libpcre2-devel -P libssl-devel -P libsqlite3-devel`
131
132
133 ===== MSYS2 =====
134
135 `pacman -Sy autoconf automake-wrapper libtool msys2-w32api-headers msys2-w32api-runtime gcc pkg-config git python openssl-devel openssl libopenssl msys2-runtime-devel gcc binutils make pcre2-devel libsqlite-devel`
136
137 === Docker containers ===
138
139 We have two repositories on DockerHub:
140 - aircrackng/release (https://hub.docker.com/r/aircrackng/release): Each release
141 - aircrackng/git (https://hub.docker.com/r/aircrackng/git): every commit in the git repository
142
143 Base command for the git version:
144 `sudo docker run --rm -it aircrackng/git`
145
146 Available platforms/CPU architectures:
147 - linux/386 (base image: debian:unstable-slim)
148 - linux/amd64 (base image: debian:unstable-slim)
149 - linux/arm/v5 (base image: debian:unstable-slim)
150 - linux/arm/v6 (base image: alpine:3)
151 - linux/arm/v7 (base image: debian:unstable-slim)
152 - linux/arm64/v8 (base image: debian:unstable-slim)
153 - linux/mips64le (base image: debian:unstable-slim)
154 - linux/ppc64le (base image: debian:unstable-slim)
155 - linux/riscv64 (base image: debian:unstable-slim)
156 - linux/s390x (base image: debian:unstable-slim)
157
158
159
160 === Compiling ===
161
162 To build `aircrack-ng`, the Autotools build system is utilized. Autotools replaces
163 the older method of compilation.
164
165 NOTE: If utilizing a developer version, eg: one checked out from source control,
166 you will need to run a pre-`configure` script. The script to use is one of the
167 following: `autoreconf -i` or `env NOCONFIGURE=1 ./autogen.sh`.
168
169 First, `./configure` the project for building with the appropriate options specified
170 for your environment:
171
172 `./configure <options>`
173
174 TIP: If the above fails, please see above about developer source control versions.
175
176 Next, compile the project (respecting if `make` or `gmake` is needed):
177
178 * Compilation:
179
180 `make`
181
182 * Compilation on *BSD or Solaris:
183
184 `gmake`
185
186 Finally, the additional targets listed below may be of use in your environment:
187
188 * Execute all unit testing:
189
190 `make check`
191
192 * Execute all integration testing (requires root):
193
194 `make integration`
195
196 * Installing:
197
198 `make install`
199
200 * Uninstall:
201
202 `make uninstall`
203
204
205 ==== `./configure` flags ====
206
207 When configuring, the following flags can be used and combined to adjust the suite
208 to your choosing:
209
210 * with-airpcap=DIR: needed for supporting airpcap devices on windows (cygwin or msys2 only)
211 Replace DIR above with the absolute location to the root of the
212 extracted source code from the Airpcap CD or downloaded SDK available
213 online. Required on Windows to build besside-ng, besside-ng-crawler,
214 easside-ng, tkiptun-ng and wesside-ng when building experimental tools.
215 The developer pack (Compatible with version 4.1.1 and 4.1.3) can be downloaded at
216 https://support.riverbed.com/content/support/software/steelcentral-npm/airpcap.html
217
218 * with-experimental: needed to compile tkiptun-ng, easside-ng, buddy-ng, buddy-ng-crawler,
219 airventriloquist and wesside-ng. libpcap development package is also
220 required to compile most of the tools.
221 If not present, not all experimental tools will be built.
222 On Cygwin, libpcap is not present and the Airpcap SDK replaces it.
223 See --with-airpcap option above.
224
225 * with-ext-scripts: needed to build `airoscript-ng`, `versuck-ng`, `airgraph-ng` and
226 `airdrop-ng`.
227 Note: Each script has its own dependencies.
228
229 * with-gcrypt: Use libgcrypt crypto library instead of the default OpenSSL.
230 And also use internal fast sha1 implementation (borrowed from GIT).
231 Dependency (Debian): libgcrypt20-dev
232
233 * with-duma: Compile with DUMA support. DUMA is a library to detect buffer overruns and underruns.
234 Dependency (Debian): duma
235
236 * disable-libnl: Set up the project to be compiled without libnl (1 or 3). Linux option only.
237
238 * without-opt: Do not enable -O3 optimizations.
239
240 * enable-shared: Make a OSdep a shared library.
241
242 * disable-shared: When combined with enable-static, it will statically compile Aircrack-ng.
243
244 * with-avx512: On x86, add support for AVX512 instructions in aircrack-ng. Only use it when
245 the current CPU supports AVX512.
246
247 * with-static-simd=<SIMD>: Compile a single optimization in aircrack-ng binary. Useful when compiling
248 statically and/or for space-constrained devices. Valid SIMD options: x86-sse2,
249 x86-avx, x86-avx2, x86-avx512, ppc-altivec, ppc-power8, arm-neon, arm-asimd.
250 Must be used with --enable-static --disable-shared. When using those 2 options, the default
251 is to compile the generic optimization in the binary. --with-static-simd merely allows
252 to choose another one.
253
254 * --enable-maintainer-mode: It is important to enable this flag when
255 developing with Aircrack-ng. This flag enables
256 additional compile warnings and safety features.
257
258 ===== Examples =====
259
260 * Configure and compiling:
261
262 `./configure --with-experimental`
263 `make`
264
265 * Compiling with gcrypt:
266
267 `./configure --with-gcrypt`
268 `make`
269
270 * Installing:
271
272 `make install`
273
274 * Installing (strip binaries):
275
276 `make install-strip`
277
278 * Installing, with external scripts:
279
280 `./configure --with-experimental --with-ext-scripts`
281 `make`
282 `make install`
283
284 * Testing (with sqlite, experimental and pcre2)
285
286 `./configure --with-experimental`
287 `make`
288 `make check`
289
290 * Compiling on OS X with macports (and all options):
291
292 `./configure --with-experimental`
293 `gmake`
294
295 * Compiling on macOS running on M1/AARCH64 and Homebrew:
296
297 `autoreconf -vif`
298 `env CPPFLAGS="-Wno-deprecated-declarations" ./configure --with-experimental`
299 `make`
300 `make check`
301
302 * Compiling on OS X 10.10 with XCode 7.1 and Homebrew:
303
304 `env CC=gcc-4.9 CXX=g++-4.9 ./configure`
305 `make`
306 `make check`
307
308 *NOTE*: Older XCode ships with a version of LLVM that does not support CPU feature
309 detection; which causes the `./configure` to fail. To work around this older LLVM,
310 it is required that a different compile suite is used, such as GCC or a newer LLVM
311 from Homebrew.
312
313 If you wish to use OpenSSL from Homebrew, you may need to specify the location
314 to its installation. To figure out where OpenSSL lives, run:
315
316 `brew --prefix openssl`
317
318 Use the output above as the DIR for `--with-openssl=DIR` in the `./configure` line:
319
320 `env CC=gcc-4.9 CXX=g++-4.9 ./configure --with-openssl=DIR`
321 `make`
322 `make check`
323
324 * Compiling on FreeBSD with gcc9
325
326 `env CC=gcc9 CXX=g++9 MAKE=gmake ./configure`
327 `gmake`
328
329 * Compiling on Cygwin with Airpcap (assuming Airpcap devpack is unpacked in Aircrack-ng directory)
330
331 ```
332 cp -vfp Airpcap_Devpack/bin/x86/airpcap.dll src
333 cp -vfp Airpcap_Devpack/bin/x86/airpcap.dll src/aircrack-osdep
334 cp -vfp Airpcap_Devpack/bin/x86/airpcap.dll src/aircrack-crypto
335 cp -vfp Airpcap_Devpack/bin/x86/airpcap.dll src/aircrack-util
336 dlltool -D Airpcap_Devpack/bin/x86/airpcap.dll -d build/airpcap.dll.def -l Airpcap_Devpack/bin/x86/libairpcap.dll.a
337 autoreconf -i
338 ./configure --with-experimental --with-airpcap=$(pwd)
339 make
340 ```
341
342 * Compiling on DragonflyBSD with gcrypt using GCC 8
343
344 ```
345 autoreconf -i
346 env CC=gcc8 CXX=g++8 MAKE=gmake ./configure --with-experimental --with-gcrypt
347 gmake
348 ```
349
350 * Compiling on OpenBSD (with autoconf 2.69 and automake 1.16)
351
352 ```
353 export AUTOCONF_VERSION=2.69
354 export AUTOMAKE_VERSION=1.16
355 autoreconf -i
356 env MAKE=gmake ./configure
357 gmake
358 ```
359
360 * Compiling and debugging aircrack-ng
361
362 ```
363 export CFLAGS='-O0 -g'
364 export CXXFLAGS='-O0 -g'
365 ./configure --with-experimental --enable-maintainer-mode --without-opt
366 make
367 LD_LIBRARY_PATH=.libs gdb --args ./aircrack-ng [PARAMETERS]
368 ```
369
370 == IDE development ==
371
372 === VS Code - devcontainers ===
373
374 A VS Code development environment is provided, as is, for rapid setup of a development environment. This additionally adds support for GitHub Codespaces.
375
376 ==== Requirements ====
377
378 The first requirement is a working Docker Engine (https://docs.docker.com/engine/install/) environment.
379
380 Next, an installation of VS Code (https://code.visualstudio.com/) with the following extension(s):
381
382 - Remote - Containers: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers by Microsoft.
383
384 Note: The "Remote - Containers" extension will refuse to work with OSS Code.
385
386 ==== Usage ====
387
388 1. Clone this repository to your working folder:
389
390 ```
391 $ git clone --recursive https://github.com/aircrack-ng/aircrack-ng.git
392 $ cd aircrack-ng
393 ```
394
395 2. After cloning this repository, open the folder inside VS Code.
396
397 ```
398 $ code .
399 ```
400
401 IMPORTANT: You should answer "Yes", if it asks if the folder should be opened inside a remote container. If it does not ask, then press `Ctrl+Shift+P` and type `open in container`. This should bring up the correct command, for which pressing enter will run said command.
402
403 3. A number of warnings might appear about a missing `compile_commands.json` file. These are safe to ignore for a moment, as this file is automatically generated after the initial compilation.
404 4. Now build the entire project by pressing `Ctrl+R` and selecting `Build Full` from the pop-up menu that appears.
405 5. VS Code should detect the `compile_commands.json` file and ask if it should be used; selecting "Yes, always" will complete the initial setup of a fully working IDE.
406 IMPORTANT: If it doesn't detect the file, pressing `Ctrl+Shift+P` and typing `reload window` will bring up the selection to fully reload the environment.
407 6. At this point, nearly all features of VS Code will function; from Intellisense, auto-completion, live documentation, to code formatting. Additionally, there are pre-configured tasks for builds and tests, as well as an example GDB/LLDB configuration for debugging `aircrack-ng`.
408
409
410 == Packaging ==
411
412 Automatic detection of CPU optimization is done at run time. This behavior
413 **is** desirable when packaging Aircrack-ng (for a Linux or other distribution.)
414
415 Also, in some cases it may be desired to provide your own flags completely and
416 not having the suite auto-detect a number of optimizations. To do this, add
417 the additional flag `--without-opt` to the `./configure` line:
418
419 `./configure --without-opt`
420
421 == Using pre-compiled binaries ==
422
423 === Linux/BSD ===
424
425 Aircrack-ng is available in most distributions repositories. However, it is not always up-to-date.
426
427 === Windows ===
428
429 * Install the appropriate "monitor" driver for your card; standard drivers don't work for capturing data.
430 * Aircrack-ng suite is command line tools. So, you have to open a command-line
431 `Start menu -> Run... -> cmd.exe` then use them
432 * Run the executables without any parameters to have help
433
434 == Documentation ==
435
436 Some more information is present in the README file.
437
438 Documentation, tutorials, ... can be found on https://aircrack-ng.org
439
440 Support is available in the GitHub Discussions (https://github.com/aircrack-ng/aircrack-ng/discussions) and on IRC (in #aircrack-ng on Libera Chat).
441
442 Every tool has its own manpage. For aircrack-ng, `man aircrack-ng`