1GOOGLE-AUTHENTICATOR(1)                                GOOGLE-AUTHENTICATOR(1)
2
3
4

NAME

6       google-authenticator  -  initialize  one-time passcodes for the current
7       user
8

SYNOPSIS

10       google-authenticator [options]
11
12       If no option is provided on the command  line,  google-authenticator(1)
13       will ask interactively the user for the more important options.
14

DESCRIPTION

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
20       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
27       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
34       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

OPTIONS

41       The main option consists of choosing the authentication token type: ei‐
42       ther time based or counter-based.
43
44       -c, --counter-based
45              Set up counter-based verification.
46
47       -t, --time-based
48              Set up time-based verification.
49
50       From this choice depends the available options.
51
52   Counter-based specific options
53       Those settings are only relevant  for  counter-based  one-time-password
54       (HOTP):
55
56       -w, --window-size=W
57              Set window of concurrently valid codes.
58
59              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
65              The window size must be between 1 and 21.
66
67       -W, --minimal-window
68              Disable window of concurrently valid codes.
69
70   Time-based specific options
71       Those  settings  are  only  relevant  for  time-based one-time-password
72       (TOTP):
73
74       -D, --allow-reuse, -d, --disallow-reuse
75              (Dis)allow multiple uses of the same authentication token.
76
77              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
81       -w, --window-size=W
82              Set window of concurrently valid codes.
83
84              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
90              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
97              The window size must be between 1 and 21.
98
99       -W, --minimal-window
100              Disable window of concurrently valid codes.
101
102       -S, --step-size=S
103              Set interval between token refreshes to S seconds.
104
105              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
109              The time interval must be between 1 and 60 seconds.
110
111   General options
112       -s, --secret=FILE
113              Specify a non-standard file location for the secret key and set‐
114              tings.
115
116       -f, --force
117              Write secret key and settings without first confirming with  us‐
118              er.
119
120       -l, --label=LABEL
121              Override the default label in otpauth:// URL.
122
123       -i, --issuer=ISSUER
124              Override the default issuer in otpauth:// URL.
125
126       -Q, --qr-mode=none|ansi|utf8
127              QRCode output mode.
128
129              Suppress the QRCode output (none), or output QRCode using either
130              ANSI colors (ansi), or Unicode block elements (utf8).
131
132              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
136       -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
139              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
143              The rate limit must be between 1 and 10 attempts.  The rate time
144              must be between 15 and 600 seconds.
145
146       -e, --emergency-codes=N
147              Generate N emergency codes.
148
149              A maximum of 10 emergency codes can be generated.
150
151       -q, --quiet
152              Quiet mode.
153
154       -h, --help
155              Print the help message.
156

SEE ALSO

158       The Google Authenticator source code and all documentation may be down‐
159       loaded from <https://github.com/google/google-authenticator-libpam>.
160
161
162
163Google two-factor authentication user manual           GOOGLE-AUTHENTICATOR(1)
Impressum