GOOGLE-AUTHENTICATOR(1)

🌸 GOOGLE-AUTHENTICATOR(1) 🌸

okay bestie, welcome to google-authenticator(1) — the manual page, but make it a group chat. this is the command that sets up one-time passcodes for whoever's logged in right now, and honestly? it's giving security era. 💅

---

✨ NAME ✨

google-authenticator — initialize one-time passcodes for the current user 🎀

---

✨ SYNOPSIS ✨

google-authenticator [options]

and listen, if you don't pass any option on the command line, google-authenticator(1) is gonna be like "hey bestie, let's chat" and ask you interactively about the more important options. it literally interviews you. 🫶

---

✨ DESCRIPTION ✨

so here's the vibe: the google-authenticator(1) command creates a brand new secret key in the current user's home directory. by default, that secret key plus all the settings live in ~/.google_authenticator. that's the home base, periodt. 🏠✨

if your system supports the libqrencode library, a QRCode gets shown, and you can scan it with the Android Google Authenticator application. iconic. 📱💖

if your system does not have that library, no worries, google-authenticator(1) outputs a URL instead, and you can follow that URL with a web browser. and alternatively, the alphanumeric secret key also gets outputted, so you can just type it manually into the Android Google Authenticator application. old school but it works. 🦋

either way, once the key has been added, you should check the verification value. to do that, the user has to click-and-hold the added entry on their Android system until the context menu shows up. then you check that the displayed key's verification value matches the one that google-authenticator(1) gave you. and pls note: this feature might not be available in all builds of the Android application. don't come for me, I'm just the messenger. 🙈

after all that? every single time the user logs into the system, they'll be prompted for the TOTP code (time based one-time-password) or HOTP (counter-based one-time-password) — depends on the options you gave to google-authenticator(1) — right after they've entered their normal user id and their normal UNIX account password. two steps, no skips. 👑

---

✨ OPTIONS ✨

the main character of this whole section is choosing the authentication token type: either time based or counter-based. pick your fighter. 🌈

• -c, --counter-based — set up counter-based verification.
• -t, --time-based — set up time-based verification.

and everything else depends on that choice, fr fr. which options you get is downstream of which lane you picked.

---

💜 Counter-based specific options 💜

okay so these settings are only relevant for counter-based one-time-password (HOTP):

• -w, --window-size=W — set window of concurrently valid codes.

by default, three tokens are valid at any one time. this accounts for generated-but-not-used tokens and failed login attempts. and if you wanna decrease the likelihood of synchronization problems, this window can be increased from its default size of 3. ngl, sometimes you just need more room. 🫶

the window size must be between 1 and 21.

• -W, --minimal-window — disable window of concurrently valid codes.

---

💖 Time-based specific options 💖

and these settings are only relevant for time-based one-time-password (TOTP):

• -D, --allow-reuse, -d, --disallow-reuse — (dis)allow multiple uses of the same authentication token.

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. so yeah, slightly more annoying, way more secure. the tradeoff is real. 🔥

• -w, --window-size=W — set window of concurrently valid codes.

by default, a new token is generated every 30 seconds by the mobile application. and 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. ⏰

for example, if you're experiencing problems with poor time synchronization, the window can be increased from its default size of 3 permitted codes (one previous code, the current code, the next code) all the way up 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. that's a whole lotta leeway. 😭

the window size must be between 1 and 21.

• -W, --minimal-window — disable window of concurrently valid codes.
• -S, --step-size=S — set interval between token refreshes to S seconds.

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. customization, we love to see it. ✨

the time interval must be between 1 and 60 seconds.

---

🎀 General options 🎀

• -s, --secret=FILE — specify a non-standard file location for the secret key and settings.
• -f, --force — write secret key and settings without first confirming with user. no take-backs, no double-checking, it just sends it. 💀
• -l, --label=LABEL — override the default label in otpauth:// URL.
• -i, --issuer=ISSUER — override the default issuer in otpauth:// URL.
• -Q, --qr-mode=none|ansi|utf8 — QRCode output mode.

suppress the QRCode output (none), or output QRCode using either ANSI colors (ansi), or Unicode block elements (utf8).

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. 😭 tragic, truly.

• -r, --rate-limit=N, -R, --rate-time=M, -u, --no-rate-limit — disable rate-limiting, or limit logins to N per every M seconds.

if the system isn't hardened against brute-force login attempts, rate-limiting can be enabled for the authentication module: no more than N login attempts every M seconds. protect the house. 🛡️

the rate limit must be between 1 and 10 attempts. the rate time must be between 15 and 600 seconds.

• -e, --emergency-codes=N — generate N emergency codes.

a maximum of 10 emergency codes can be generated. keep 'em somewhere safe, bestie, they're your backup plan. 🚨

• -q, --quiet — quiet mode.
• -h, --help — print the help message.

---

✨ SEE ALSO ✨

the Google Authenticator source code and all documentation may be downloaded from <https://github.com/google/google-authenticator-libpam>. go read it, it's free, it's iconic. 📚💖

---

and that's the whole page, bestie! 🫶 this was google-authenticator(1) from the Google two-factor authentication use... project — the footer was kinda shy and got cut off, but you get the vibe. stay secure out there, and remember: no cap, always check your verification value. 👑💅✨