.\" Automatically generated by Pandoc 1.16.0.2
.\"
.TH "GOOGLE\-AUTHENTICATOR" "1" "" "Google two\-factor authentication user manual" ""
.hy
.SH NAME
.PP
google\-authenticator \- initialize one\-time passcodes for the current
user
.SH SYNOPSIS
.PP
google\-authenticator [\f[I]options\f[]]
.PP
If no option is provided on the command line, google\-authenticator(1)
will ask interactively the user for the more important options.
.SH DESCRIPTION
.PP
The google\-authenticator(1) command creates a new secret key in the
current user\[aq]s home directory.
By default, this secret key and all settings will be stored in
\f[C]~/.google_authenticator\f[].
.PP
If the system supports the \f[C]libqrencode\f[] library, a QRCode will
be shown, that can be scanned using the Android Google Authenticator
application.
If the system does not have this library, google\-authenticator(1)
outputs an URL that can be followed using a web browser.
Alternatively, the alphanumeric secret key is also outputted and thus can
be manually entered into the Android Google Authenticator application.
.PP
In either case, after the key has been added, the verification value
should be checked.
To do that, the user must click\-and\-hold the added entry on its
Android system until the context menu shows.
Then, the user checks that the displayed key\[aq]s verification value
matches the one provided by google\-authenticator(1).
Please note that this feature might not be available in all builds of
the Android application.
.PP
Each time the user logs into the system, he will now be prompted for the
TOTP code (time based one\-time\-password) or HOTP (counter\-based
one\-time\-password), depending on options given to
google\-authenticator(1), after having entered its normal user id and
its normal UNIX account password.
.SH OPTIONS
.PP
The main option consists of choosing the authentication token type:
either time based or counter\-based.
.TP
.B \-c, \-\-counter\-based
Set up counter\-based verification.
.RS
.RE
.TP
.B \-t, \-\-time\-based
Set up time\-based verification.
.RS
.RE
.PP
From this choice depends the available options.
.SS Counter\-based specific options
.PP
Those settings are only relevant for counter\-based one\-time\-password
(HOTP):
.TP
.B \-w, \-\-window\-size=\f[I]W\f[]
Set window of concurrently valid codes.
.RS
.PP
By default, three tokens are valid at any one time.
This accounts for generated\-but\-not\-used tokens and failed login
attempts.
In order to decrease the likelihood of synchronization problems, this
window can be increased from its default size of 3.
.PP
The window size must be between 1 and 21.
.RE
.TP
.B \-W, \-\-minimal\-window
Disable window of concurrently valid codes.
.RS
.RE
.SS Time\-based specific options
.PP
Those settings are only relevant for time\-based one\-time\-password
(TOTP):
.TP
.B \-D, \-\-allow\-reuse, \-d, \-\-disallow\-reuse
(Dis)allow multiple uses of the same authentication token.
.RS
.PP
This restricts the user to one login about every 30 seconds, but it
increases the chances to notice or even prevent man\-in\-the\-middle
attacks.
.RE
.TP
.B \-w, \-\-window\-size=\f[I]W\f[]
Set window of concurrently valid codes.
.RS
.PP
By default, a new token is generated every 30 seconds by the mobile
application.
In order to compensate for possible time\-skew between the client and
the server, an extra token before and after the current time is allowed.
This allows for a time skew of up to 30 seconds between authentication
server and client.
.PP
For example, if problems with poor time synchronization are experienced,
the window can be increased from its default size of 3 permitted codes
(one previous code, the current code, the next code) to 17 permitted
codes (the 8 previous codes, the current code, and the 8 next codes).
This will permit for a time skew of up to 4 minutes between client and
server.
.PP
The window size must be between 1 and 21.
.RE
.TP
.B \-W, \-\-minimal\-window
Disable window of concurrently valid codes.
.RS
.RE
.TP
.B \-S, \-\-step\-size=\f[I]S\f[]
Set interval between token refreshes to \f[I]S\f[] seconds.
.RS
.PP
By default, time\-based tokens are generated every 30 seconds.
A non\-standard value can be configured in case a different time\-step
value must be used.
.PP
The time interval must be between 1 and 60 seconds.
.RE
.SS General options
.TP
.B \-s, \-\-secret=\f[I]FILE\f[]
Specify a non\-standard file location for the secret key and settings.
.RS
.RE
.TP
.B \-f, \-\-force
Write secret key and settings without first confirming with user.
.RS
.RE
.TP
.B \-l, \-\-label=\f[I]LABEL\f[]
Override the default label in \f[C]otpauth://\f[] URL.
.RS
.RE
.TP
.B \-i, \-\-issuer=\f[I]ISSUER\f[]
Override the default issuer in \f[C]otpauth://\f[] URL.
.RS
.RE
.TP
.B \-Q, \-\-qr\-mode=\f[I]none|ansi|utf8\f[]
QRCode output mode.
.RS
.PP
Suppress the QRCode output (\f[I]none\f[]), or output QRCode using
either ANSI colors (\f[I]ansi\f[]), or Unicode block elements
(\f[I]utf8\f[]).
.PP
Unicode block elements makes the QRCode much smaller, which is often
easier to scan.
Unfortunately, many terminal emulators do not display these Unicode
characters properly.
.RE
.TP
.B \-r, \-\-rate\-limit=\f[I]N\f[], \-R, \-\-rate\-time=\f[I]M\f[], \-u, \-\-no\-rate\-limit
Disable rate\-limiting, or limit logins to N per every M seconds.
.RS
.PP
If the system isn\[aq]t hardened against brute\-force login attempts,
rate\-limiting can be enabled for the authentication module: no more
than \f[I]N\f[] login attempts every \f[I]M\f[] seconds.
.PP
The rate limit must be between 1 and 10 attempts.
The rate time must be between 15 and 600 seconds.
.RE
.TP
.B \-e, \-\-emergency\-codes=\f[I]N\f[]
Generate \f[I]N\f[] emergency codes.
.RS
.PP
A maximum of 10 emergency codes can be generated.
.RE
.TP
.B \-q, \-\-quiet
Quiet mode.
.RS
.RE
.TP
.B \-h, \-\-help
Print the help message.
.RS
.RE
.SH SEE ALSO
.PP
The Google Authenticator source code and all documentation may be
downloaded from <https://github.com/google/google-authenticator-libpam>.