Text of korg.docs.kernel.org › gitolite › 2fa.html as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

2-factor authentication with gitolite (deprecated) — Kernel.org Documentation documentation

2-factor authentication with gitolite (deprecated) View page source 2-factor authentication with gitolite (deprecated)  Warning The preferred mechanism for 2-factor authentication is via an SSH key stored on a smartcard device. See 2-factor auth with FIDO2 keys for instructions on how to set up a FIDO2 device for this purpose. If you have an account on kernel.org, you qualify for a free nitrokey (see Obtaining and setting up your Nitrokey ).

HOTP/TOTP ssh session push validation  Note This is entirely opt-in. Command Summary enroll [mode] Enroll with 2-factor authentication (mode=totp or yubikey) val-session [token] Validate your current ssh ControlMaster session val [token] Alias for val-session command isval Check if your current session is validated unenroll [token] Unenroll from 2-factor authentication Core concepts  Once 2-factor authentication is enabled for a git repository, any write operation from ssh session that hasn’t been 2-factor validated will be rejected with a message like the following: remote: User not enrolled with 2-factor authentication. remote: FATAL: W VREF/2fa: testing mricon DENIED by VREF/2fa remote: 2-factor verification failed remote: remote: You will need to enroll with 2-factor authentication remote: before you can push to this repository. remote: remote: If you need more help, please see the following link: remote: https://korg.wiki.kernel.org/index.php?title=Userdoc:gitolite_2fa remote: remote: error: hook declined to update refs/heads/master To allow the push to succeed, you will need to first validate your ssh session with your 2-factor token, which will allow all subsequent pushes to succeed.

Once your ssh controlmaster session is terminated, your validation will expire and you will need to re-validate it next time. Example: ssh git@gitolite.kernel.org 2fa val XXXXXX Read operations should be completely unaffected. SSH configuration  Before you can use this feature, you will need to make sure you enabled ssh multiplexing in the client, by adding the following entries to your gitolite.kernel.org section: ControlPath ~/.ssh/cm-%r@%h:%p ControlMaster auto ControlPersist 30m You can use longer than 30m if desired.

It will expire automatically or whenever your network connection goes away. To manually terminate your session, run: ssh -O exit git@gitolite.kernel.org Please see How to set up your ssh access for more ssh setup details. Supported devices  We implement both HOTP ( RFC 4226 ) and TOTP ( RFC 6238 ) parts of the OATH standard. Since TOTP soft-tokens are easiest to enroll and provision to such a dispersed crowd as kernel developers – and since most kernel developers have access to a smartphone that they carry with them around anyway – TOTP is the preferred mechanism.

TOTP apps  In your smartphone’s app directory, you should be able to find one of the following applications (links given to Google Play store, but should exist on iOS as well): FreeOTP (preferred, free software) Google Authenticator (proprietary) Authy (proprietary) HOTP devices  The only HOTP devices currently tested and supported are yubikeys. Any of the currently listed products should support HOTP authentication.

Laptop users may find that using the Nano form factor is more comfortable. Provisioning your 2-factor token  There is a special 2fa command in gitolite, used to interact with the 2-factor validation component. To provision, you submit a command via the gitolite interface. TOTP soft-token apps  To enroll a TOTP soft-token app, such as FreeOTP or Google Authenticator, run: ssh git@gitolite.kernel.org 2fa enroll totp This command outputs the following: totp enrollment mode selected New token generated for user mricon Please make sure "qrencode" is installed.

Run the following commands to display your QR code: unset HISTFILE qrencode -tANSI -m1 -o- "otpauth://totp/mricon@gitolite.kernel.org?secret=ACHQKMJFHIXJDNRY" If that does not work or if you do not have access to qrencode or a similar QR encoding tool, then you may open an INCOGNITO/PRIVATE MODE window in your browser and paste the following URL: https://www.google.com/chart?chs=200x200&chld=M|0&cht=qr&chl=otpauth%3A%2F%2Ftotp%2Fmricon%40gitolite.kernel.org%3Fsecret%3DACHQKMJFHIXJDNRY Scan the resulting QR code with your TOTP app, such as FreeOTP (recommended), Google Authenticator, Authy, or others.

Please write down/print the following 8-digit scratch tokens. If you lose your device or temporarily have no access to it, you will be able to use these tokens for one-time bypass. Scratch tokens: 19489805 36196876 06341363 70324458 39448548 Now run the following command to verify that all went well ssh git@gitolite.kernel.org 2fa val [token] If you need more help, please see the following link: https://korg.docs.kernel.org/gitolite/2fa.html Note Please remember to unset HISTFILE or your secret will be stored in your ~/.bash_history.

Alternatively, if you absolutely have no other way to locally generate a QR code, it is important to actually open a new “Incognito/Private Mode” window to make sure that the URL containing your 2-factor secret is not saved in your browser history. Note, that if you do use the Google link, you’ll be giving your 2-factor secret to Google – whatever that implies. Yubikeys  To initialize a yubikey, run the following command instead.

Note, that you will need ykpersonalize to configure your key: ssh git@gitolite.kernel.org 2fa enroll yubikey The output of the yubikey command is slightly different: yubikey enrollment mode selected New token generated for user mricon Please make sure "ykpersonalize" has been installed. Insert your yubikey and, as root, run the following command to provision the secret into slot 1 (use -2 for slot 2): unset HISTFILE ykpersonalize -1 -ooath-hotp -oappend-cr -a7fd554b1e4a711155d20e9f9615b0451152db3bb Please write down/print the following 8-digit scratch tokens.

If you lose your device or temporarily have no access to it, you will be able to use these tokens for one-time bypass. Scratch tokens: 88989251 08286736 73163062 90775064 59235228 Now run the following command to verify that all went well ssh git@gitolite.kernel.org 2fa val [yubkey button press] If you need more help, please see the following link: https://korg.docs.kernel.org/gitolite/2fa.html It is important to use ``unset HISTFILE`` to make sure the secret isn’t saved in your ~/.bash_history.

Additionally, you may also omit the -a flag and ykpersonalize should prompt you for the secret, in which case paste the string that follows the -a (but not -a itself). Testing your 2fa token  You can test things on the special “testing” repository: git clone git@gitolite.kernel.org:testing cd testing git checkout -b [username] Edit the README file, commit, and try to push: git push origin [username] You should get the following back: Counting objects: 7, done.

Delta compression using up to 4 threads. Compressing objects: 100% (2/2), done. Writing objects: 100% (3/3), 308 bytes | 0 bytes/s, done. Total 3 (delta 1), reused 0 (delta 0) remote: FATAL: W VREF/2fa: testing mricon DENIED by VREF/2fa remote: 2-factor verification failed remote: remote: Please get your 2-factor authentication token and run: remote: ssh git@gitolite.kernel.org 2fa val [token] remote: remote: Make sure your ssh is using ControlMaster connections. remote: remote: If you need more help, please see the following link: remote: https://korg.docs.kernel.org/gitolite/2fa.html remote: remote: error: hook declined to update refs/heads/mricon To git@gitolite.kernel.org:testing ! [remote rejected] mricon -> mricon (hook declined) error: failed to push some refs to 'git@gitolite.kernel.org:testing' As instructed, run the following: $ ssh git@gitolite.kernel.org 2fa val [token] Valid TOTP token within window size used If you now try the push again, it will succeed: $ git push origin mricon Counting objects: 7, done.

Delta compression using up to 4 threads. Compressing obje

The rest of this page is on the live site.