1GOOGLE-AUTHENTICATOR(1) GOOGLE-AUTHENTICATOR(1)
2
6 google-authenticator - initialize one-time passcodes for the current
7 user
8
10 google-authenticator [options]
11 If no option is provided on the command line, google-authenticator(1)
13 will ask interactively the user for the more important options.
14
16 The google-authenticator(1) command creates a new secret key in the
17 current user's home directory. By default, this secret key and all
18 settings will be stored in ~/.google_authenticator.
19 If the system supports the libqrencode library, a QRCode will be shown,
21 that can be scanned using the Android Google Authenticator application.
22 If the system does not have this library, google-authenticator(1) out‐
23 puts an URL that can be followed using a web browser. Alternatively,
24 the alphanumeric secret key is also outputed and thus can be manually
25 entered into the Android Google Authenticator application.
26 In either case, after the key has been added, the verification value
28 should be checked. To do that, the user must click-and-hold the added
29 entry on its Android system until the context menu shows. Then, the
30 user checks that the displayed key's verification value matches the one
31 provided by google-authenticator(1). Please note that this feature
32 might not be available in all builds of the Android application.
33 Each time the user logs into the system, he will now be prompted for
35 the TOTP code (time based one-time-password) or HOTP (counter-based
36 one-time-password), depending on options given to google-authentica‐
37 tor(1), after having entered its normal user id and its normal UNIX ac‐
38 count password.
39
41 The main option consists of choosing the authentication token type: ei‐
42 ther time based or counter-based.
43 -c, --counter-based
45 Set up counter-based verification.
46 -t, --time-based
48 Set up time-based verification.
49 From this choice depends the available options.
51 Counter-based specific options
53 Those settings are only relevant for counter-based one-time-password
54 (HOTP):
55 -w, --window-size=W
57 Set window of concurrently valid codes.
58 By default, three tokens are valid at any one time. This ac‐
60 counts for generated-but-not-used tokens and failed login at‐
61 tempts. In order to decrease the likelihood of synchronization
62 problems, this window can be increased from its default size of
63 3.
64 The window size must be between 1 and 21.
66 -W, --minimal-window
68 Disable window of concurrently valid codes.
69 Time-based specific options
71 Those settings are only relevant for time-based one-time-password
72 (TOTP):
73 -D, --allow-reuse, -d, --disallow-reuse
75 (Dis)allow multiple uses of the same authentication token.
76 This restricts the user to one login about every 30 seconds, but
78 it increases the chances to notice or even prevent
79 man-in-the-middle attacks.
80 -w, --window-size=W
82 Set window of concurrently valid codes.
83 By default, a new token is generated every 30 seconds by the mo‐
85 bile application. In order to compensate for possible time-skew
86 between the client and the server, an extra token before and af‐
87 ter the current time is allowed. This allows for a time skew of
88 up to 30 seconds between authentication server and client.
89 For example, if problems with poor time synchronization are ex‐
91 perienced, the window can be increased from its default size of
92 3 permitted codes (one previous code, the current code, the next
93 code) to 17 permitted codes (the 8 previous codes, the current
94 code, and the 8 next codes). This will permit for a time skew
95 of up to 4 minutes between client and server.
96 The window size must be between 1 and 21.
98 -W, --minimal-window
100 Disable window of concurrently valid codes.
101 -S, --step-size=S
103 Set interval between token refreshes to S seconds.
104 By default, time-based tokens are generated every 30 seconds. A
106 non-standard value can be configured in case a different
107 time-step value must be used.
108 The time interval must be between 1 and 60 seconds.
110 General options
112 -s, --secret=FILE
113 Specify a non-standard file location for the secret key and set‐
114 tings.
115 -f, --force
117 Write secret key and settings without first confirming with us‐
118 er.
119 -l, --label=LABEL
121 Override the default label in otpauth:// URL.
122 -i, --issuer=ISSUER
124 Override the default issuer in otpauth:// URL.
125 -Q, --qr-mode=none|ansi|utf8
127 QRCode output mode.
128 Suppress the QRCode output (none), or output QRCode using either
130 ANSI colors (ansi), or Unicode block elements (utf8).
131 Unicode block elements makes the QRCode much smaller, which is
133 often easier to scan. Unfortunately, many terminal emulators do
134 not display these Unicode characters properly.
135 -r, --rate-limit=N, -R, --rate-time=M, -u, --no-rate-limit
137 Disable rate-limiting, or limit logins to N per every M seconds.
138 If the system isn't hardened against brute-force login attempts,
140 rate-limiting can be enabled for the authentication module: no
141 more than N login attempts every M seconds.
142 The rate limit must be between 1 and 10 attempts. The rate time
144 must be between 15 and 600 seconds.
145 -e, --emergency-codes=N
147 Generate N emergency codes.
148 A maximum of 10 emergency codes can be generated.
150 -q, --quiet
152 Quiet mode.
153 -h, --help
155 Print the help message.
156
158 The Google Authenticator source code and all documentation may be down‐
159 loaded from <https://github.com/google/google-authenticator-libpam>.
160Google two-factor authentication user manual GOOGLE-AUTHENTICATOR(1)