Openwall GNU/*/Linux - a small security-enhanced Linux distro for servers

John the Ripper's command line syntax.

When invoked with no command line arguments, "john" prints its usage summary.

The supported command line arguments are password file names and options. Many of the supported options accept additional arguments.

You can list any number of password files right on the command line of "john". You do not have to specify any options. If valid password files are specified but no options are given, John will go through the default selection of cracking modes with their default settings.

Options may be specified along with password files or on their own, although some require that password files be specified and some do not support operation on password files.

All options are case sensitive, can be abbreviated as long as the abbreviations are unambiguous, can be prefixed with two dashes (GNU-style) or with one dash, and can use "=" or ":" to indicate an argument (if supported for a given option).

The supported options are as follows, square brackets denote optional arguments:

--single			"single crack" mode

Enables the "single crack" mode, using rules from the configuration file section [List.Rules:Single].

--wordlist=FILE			wordlist mode, read words from FILE,
--stdin				or from stdin

These are used to enable the wordlist mode.

--rules				enable word mangling rules for wordlist mode

Enables word mangling rules that are read from [List.Rules:Wordlist].

--incremental[=MODE]		"incremental" mode [using section MODE]

Enables the "incremental" mode, using the specified configuration file definition (section [Incremental:MODE]). If MODE is omitted, the default is "ASCII" for most hash types and "LM_ASCII" for LM hashes.

--external=MODE			external mode or word filter

Enables an external mode, using external functions defined in section [List.External:MODE].

--stdout[=LENGTH]		just output candidate passwords

When used with a cracking mode, except for "single crack", makes John output the candidate passwords it generates to stdout instead of actually trying them against password hashes; no password files may be specified when this option is used. If a LENGTH is given, John assumes that to be the significant password length and only produces passwords up to that length.

--restore[=NAME]		restore an interrupted session

Continues an interrupted cracking session, reading state information from the specified session file or from $JOHN/john.rec by default.

--session=NAME			give a new session the NAME

This option can only be used when starting a new cracking session and its purpose is to give the new session a name (to which John will append the ".rec" suffix to form the session file name). This is useful for running multiple instances of John in parallel or to be able to later recover a session other than the last one you interrupt.

--status[=NAME]			print status of a session [called NAME]

Prints status of an interrupted or running session. Note that on a Unix-like system, you can get a detached running session to update its session file by sending a SIGHUP to the appropriate "john" process; then use this option to read in and display the status.

--make-charset=FILE		make a charset, overwriting FILE

Generates a charset file based on character frequencies from $JOHN/john.pot, for use with the "incremental" mode. The entire $JOHN/john.pot will be used for the charset generation by default. You may restrict the set of passwords used by specifying some password files (in which case only the cracked passwords that correspond to those password files will be used), "--format", or/and "--external" (with an external mode that defines a filter() function).

--show				show cracked passwords

Shows the cracked passwords for given password files (which you must specify). You can use this option while another instance of John is cracking to see what John did so far; to get the most up to date information, first send a SIGHUP to the appropriate "john" process.

--test[=TIME]			run tests and benchmarks for TIME seconds each

Tests all of the compiled in hashing algorithms for proper operation and benchmarks them. The "--format" option can be used to restrict this to a specific algorithm.

--users=[-]LOGIN|UID[,..]	[do not] load this (these) user(s)

Allows you to select just a few accounts for cracking or for other operations. A dash before the list can be used to invert the check (that is, load information for all the accounts that are not listed).

--groups=[-]GID[,..]		load users [not] of this (these) group(s)

Tells John to load (or to not load) information for accounts in the specified group(s) only.

--shells=[-]SHELL[,..]		load users with[out] this (these) shell(s)

This option is useful to load accounts with a valid shell only or to not load accounts with a bad shell. You can omit the path before a shell name, so "--shells=csh" will match both "/bin/csh" and "/usr/bin/csh", while "--shells=/bin/csh" will only match "/bin/csh".

--salts=[-]N			load salts with[out] at least N passwords

This is a feature which allows to achieve better performance in some special cases. For example, you can crack only some salts using "--salts=2" faster and then crack the rest using "--salts=-2". Total cracking time will be about the same, but you will likely get some passwords cracked earlier.

--save-memory=LEVEL		enable memory saving, at LEVEL 1..3

You might need this option if you don't have enough memory or don't want John to affect other processes too much. Level 1 tells John to not waste memory on login names; it is only supported when a cracking mode other than "single crack" is explicitly requested. The only impact is that you won't see the login names while cracking. Higher memory saving levels have a performance impact; you should probably avoid using them unless John doesn't work or gets into swap otherwise.

--node=MIN[-MAX]/TOTAL		this node's number range out of TOTAL count

This option is intended to allow for some trivial manually-configured parallel and distributed processing. For example, to split the workload across two nodes (which could be machines, CPU cores, etc.), you'd specify "--node=1/2" on one invocation of John and "--node=2/2" on the other. (If you do this on just one machine and with the same build of John, you will also need to specify different "--session" names for the two simultaneous invocations.) The nodes are assumed to be same speed (if this is not the case, one will get ahead of the other and is likely to be done sooner, unless you're using a cracking mode and settings such that the session is not expected to ever "complete" - which is fine.) If your nodes are of very different speed, you may compensate for that by allocating ranges of node numbers to individual invocations. For example, if you use OpenMP-enabled builds of John on two machines, OpenMP is supported (with good scalability) for the hash type you're cracking, and one of the machines has twice more of similar speed CPU cores than the other, then you may use "--node=1-2/3" on the twice bigger machine (let it be nodes 1 and 2 out of 3 nodes total) and "--node=3/3" on the smaller one.

Efficiency of this approach to parallel processing, as currently implemented, varies by cracking mode and its settings (efficiency is higher for incremental mode and for wordlist mode with many rules, and lower for other cracking modes and for wordlist mode without rules or with few rules), hash type (efficiency is higher for slower to compute hashes), salt count (efficiency is higher for higher salt counts), and node count (efficiency is higher for lower node counts). Scalability may be limited. The highest node count you can reasonably use varies by cracking mode, its settings, hash type, and salt count. With incremental mode, efficiency in terms of c/s rate is nearly perfect (there's essentially no overhead), but some nodes may currently receive too little work - and this problem is exacerbated by high node counts (such as 100 or more) and/or restrictive settings (such as MinLen and MaxLen set to the same value or to a narrow range, and/or a charset file with few characters being used). With wordlist mode, for high efficiency the rule count (after preprocessor expansion) needs to be many times higher than node count, unless the p/s rate is low anyway (due to slow hash type and/or high salt count).

Since there's no communication between the nodes, hashes successfully cracked by one node continue being cracked by other nodes. This is mostly OK for saltless hash types or when there's just one salt (since the same number of hash computations is to be made anyway - namely, only one per candidate password tested), but it is a serious drawback when many different salts are present and their number could potentially be decreasing as some hashes get cracked.

--fork=N			fork N processes

This option is only available on Unix-like systems. It is an easy way to make use of multiple CPUs or CPU cores - you simply specify the number of John processes that you'd like to run. You may use "--fork" as an alternative to OpenMP, for formats currently lacking OpenMP support, or/and along with OpenMP (e.g., on a machine with 64 logical CPUs you might choose to run with "--fork=8" for 8 processes and use OpenMP to run 8 threads per process).

You may use "--fork" along with "--node" to use multiple machines while also running multiple John processes per machine. For example, to use two similar 8-core machines you may run "--fork=8 --node=1-8/16" on one of the machines and "--fork=8 --node=9-16/16" on the other. For a more complicated example, if you have an 8-core machine and a 64-core machine with similar per-core performance, you could run an OpenMP-enabled build on both of them and use "--node=1/9" (without "--fork") on the first machine (8 threads in 1 process) and "--fork=8 --node=2-9/9" on the 64-core machine (8 threads in 8 processes, for 64 threads total on this machine). With the current implementation, the node numbers range assigned to each John invocation must match the "--fork" process count.

When running with "--fork", multiple ".rec" files are created, which are then read back by "--status" and "--restore" if you use those options. Just like with other options, you must not specify "--fork" along with "--status" or "--restore", because these read the main (unnumbered) ".rec" file first, which contains the right "--fork" option in it, resulting in further (numbered) ".rec" files being read as appropriate.

Under the hood, "--fork" makes use of the same functionality that "--node" does, so the same efficiency and scalability limitations apply. Despite of those, "--fork" is often much more efficient than OpenMP - especially for fast to compute hash types (such as LM hashes), where OpenMP overhead is often unacceptable.

Similarly to "--node", there's almost no communication between the processes with "--fork". Hashes successfully cracked by one process continue being cracked by other processes. Just like with "--node", this is mostly OK for saltless hash types or when there's just one salt, but it is a serious drawback when many different salts are present and their number could potentially be decreasing as some hashes get cracked. To have the cracked hashes (and possibly salts) removed from all processes, you may interrupt and restore the session once in a while.

--format=NAME			force hash type NAME

Allows you to override the hash type detection. As of John the Ripper version 1.8.0, valid "format names" are descrypt, bsdicrypt, md5crypt, bcrypt, LM, AFS, tripcode, dummy, and crypt (and many more are added in jumbo). You can use this option when you're starting a cracking session or along with one of: "--test", "--show", "--make-charset". Note that John can't crack hashes of different types at the same time. If you happen to get a password file that uses more than one hash type, then you have to invoke John once for each hash type and you need to use this option to make John crack hashes of types other than the one it would autodetect by default.

"--format=crypt" may or may not be supported in a given build of John. In default builds of John, this support is currently only included on Linux and Solaris. When specified (and supported), this option makes John use the system's crypt(3) or crypt_r(3) function. This may be needed to audit password hashes supported by the system, but not yet supported by John's own optimized cryptographic routines. Currently, this is the case for glibc 2.7+ SHA-crypt hashes as used by recent versions of Fedora and Ubuntu, and for SunMD5 hashes supported (but not used by default) on recent versions of Solaris. In fact, you do not have to explicitly specify "--format=crypt" for hashes of these specific types unless you have other hash types (those supported by John natively) in the password file(s) as well (in which case another hash type may get detected unless you specify this option).

"--format=crypt" is also a way to make John crack crypt(3) hashes of different types at the same time, but doing so results in poor performance and in unnecessarily poor results (in terms of passwords cracked) for hashes of the "faster" types (as compared to the "slower" ones loaded for cracking at the same time). So you are advised to use separate invocations of John, one per hash type.

Additional utilities (compiled/installed along with John).

There are some related utilities in John's run directory. (Depending on platform, these may be symlinks to the main John program binary.)

	unshadow PASSWORD-FILE SHADOW-FILE

Combines the "passwd" and "shadow" files (when you already have access to both) for use with John. You might need this since if you only used your shadow file, the "Full Name" or "GECOS" information wouldn't be used by the "single crack" mode (thus reducing its efficiency) and you wouldn't be able to use the "--groups" and "--shells" options and to select by UID with "--users". You probably also want to see all of the passwd file fields with "--show".

You'll usually want to redirect the output of "unshadow" to a file which you then pass to John.

	unafs DATABASE-FILE CELL-NAME

Gets password hashes out of the binary AFS database and produces output usable by John (you should redirect the output to a file).

	unique OUTPUT-FILE

Removes duplicates from a wordlist (read from stdin) without changing the order of entries. You might want to use this with John's "--stdout" option if you've got a lot of disk space to trade for the reduced cracking time (on possibly trying some duplicates as they might be produced with word mangling rules).

Scripts.

There are also some related scripts supplied in John's run directory. (Binary packages of John may choose to install these along with the documentation instead.)

	relbench BENCHMARK-FILE-1 BENCHMARK-FILE-2

relbench is a Perl script to compare two "john --test" benchmark runs, such as for different machines, "make" targets, C compilers, optimization options, or/and versions of John the Ripper. To use it, redirect the output of each "john --test" run to a file, then run the script on the two files. Most values output by the script indicate relative performance seen on the second benchmark run as compared to the first one, with the value of 1.0 indicating no change, values higher than 1.0 indicating speedup, and values lower than 1.0 indicating slowdown. Specifically, the script outputs the minimum, maximum, median, and geometric mean for the speedup (or slowdown) seen across the many individual benchmarks that "john --test" performs. It also outputs the median absolute deviation (relative to the median) and geometric standard deviation (relative to the geometric mean). Of these two, a median absolute deviation of 0.0 would indicate that no deviation from the median is prevalent, whereas a geometric standard deviation of 1.0 would indicate that all benchmarks were sped up or slowed down by the exact same ratio or their speed remained unchanged. In practice, these values will tend to deviate from 0.0 and 1.0, respectively.

	mailer PASSWORD-FILE

A shell script to send mail to all users whose passwords got cracked. This is not always a good idea, though, since lots of people do not check their e-mail or ignore such messages, and the messages can be a hint for crackers.

You should probably deploy proactive password strength checking, such as with passwdqc, before you ask users to change their passwords - whether using this script or otherwise. And you should edit the message inside the script before possibly using it.

	makechr

This is a script to (re-)generate the .chr files using passwords in john.pot and applying all of the defined external mode filters. To speed it up on a sufficiently large computer (RAM and CPUs), "&" may be added after the John invocation inside the script (to run all of them in parallel).

$Owl: Owl/packages/john/john/doc/OPTIONS,v 1.19 2013/05/29 20:20:08 solar Exp $

Powered by Openwall GNU/*/Linux - Powered by OpenVZ