Tag: 2fa

Enable 2FA for TrueNAS Core

Enable 2FA for TrueNAS Core

The 2FA in TrueNAS Core uses pam_oath.so module, supports Two-factor time based (TOTP) SSH authentication.


Enable 2FA

  • Go to Credentials => 2FA

  • Click on Enable Two-Factor Authentication

  • Click on Show QR, use Authy to record it. This is token for root account.

  • Save

Test GUI

Use another browser login with user name, password, and pin code (Authy generated).

Make sure it is working.

Enable SSH

  • Go to Credentials => 2FA

  • Select Enable Two-Factor Auth for SSH

  • Save

Enable root login

  • Go to System Settings => Services

  • Select Configure button, which is a pencil icon

  • Check Log in as Root with Password

  • Save

Test root login with 2FA

Use terminal

$ ssh host.example.com
One-time password (OATH) for 'root':
Linux truenas.bx.net 5.10.70+truenas #1 SMP Wed Nov 3 18:30:34 UTC 2021 x86_64

Test root login successful.

Disable root login

  • Go to System Settings => Services

  • Select Configure button, which is a pencil icon

  • Uncheck Log in as Root with Password

  • Save

Setup for normal user

After enable 2FA, normal user can not login, got error in /var/log/auth.log as below:

error: PAM: User not known to the underlying authentication module for ...

Use these steps to enable 2FA for user.

Note: If you lost SSH connection, the root shell can be accessed from GUI, System Settings => Shell

Generate a random code

# head -10 /dev/urandom | md5sum | cut -b 1-30

Get oath configuration file name

The usersfile name can be found using following command:

# grep oath /etc/pam.d/sshd
auth    required    pam_oath.so    usersfile=/etc/users.oath    window=0

Update /etc/users.oath

Setup the oath seed in /etc/users.oath:

HOTP/T30/6  user    -   15ad027b56c81672214f4659ffb432

Install oathtool

Use another linux server, such as ubuntu server:

ubuntu# apt install oathtool

I chose another server, because TrueNAS server is not fully customized debian server, better don't change it structure and packages.

Test pin code for SSH

Open another terminal, and run following command, and run second command in the linux server when prompting OATH code.

$ ssh host.example.com
One-time password (OATH) for 'user':

Now, quickly run following command,

ubuntu# oathtool --totp -v 15ad027b56c81672214f4659ffb432

Input OATH code in SSH login terminal. The code should be accepted.

Get Base32 secret

In the previous ubuntu server, install qrencode package

ubuntu# apt install qrencode

Run following command to collect Base32 secret:

ubuntu# oathtool --totp -v 15ad027b56c81672214f4659ffb432
Hex secret: 15ad027b56c81672214f4659ffb432

Generate QR code

qrencode -t ansiutf8 "otpauth://totp/user@host.example.com?secret=CWWQE62WZALHEIKPIZM77NBS"

Save into Authy

Use Authy scan QR code, then type in TrueNAS in textbox to search icon, then save it.

Persistent change

As TrueNAS is a fully customized OS, it has startup process to regenerate /etc/users.oath file, results only root id stays.

In order to overcome this issue, create a startup command in System Settings => Advanced => Init/Shutdown Scripts, add following command:

Name: Append oath codes

echo "HOTP/T30/6\t<user_name>\t-\t<user_code>" >> /etc/users.oath

Note: There are many ways to archive this, such as backup users.oath files you created, and restore it. I just chose the most easy and maintenance free way.


I could not find any place to setup in TrueNAS GUI for user, and the user id I created in TrueNAS can not login to GUI at all. In fact, TrueNAS doesn't support normal user login to GUI.

Possible enhancements

There are the limitations of pam_oath.o implemenation

Only one usersfile

Only one usersfile can be specified in pam_oath.o, there are some suggestions, such as:

  • Enhance source code to allow pam_oath.o accepts %h as usersfile parameter's value to point to user's home directory.

Missing entry allowed

If the user is not in usersfile, then they can not login, this makes administrator very busy.

I like one example implementation as below:

WARNING: I didn't test the following codes which downloaed from Two-Factor Authentication with OTP (Admin Guide), just for reference.

  • Create a group called otpusers, the users are not in this group do not require 2FA. This implemented in PAM
auth [success=2 default=ignore] pam_succeed_if.so uid = 0                        # skip 2 lines for root
auth [success=1 default=ignore] pam_succeed_if.so user notingroup otpusers       # ignore users not yet in otpusers
auth requisite pam_oath.so usersfile=/var/security/auth/users.oath window=20     # accept one of 20 consecutive keys 
 (in case clocks of user and server are out of sync)

* Create profile script to check whether the user is in `otpusers` group, if not, create oath code and allow user save it.

*WARNING: The below script that I copied from Internet got syntax error, and I didn't test it as well.*



RRZK, 2015-12-10 (CO)





/usr/bin/id -Gn ${ME}|/bin/grep ${OTPGROUP} >/dev/null 2>&1

if [ ! ${ME} = "root" ] && [ ${RET} -ne 0 ]; then

Disable CTRL-C

trap '' 2

/bin/echo -e "

Hello ${ME}

I will generate a TOTP (time based) OATH Secret for you...

generate secret

/bin/echo "... generating secret"
SECRET=$(/usr/bin/head -10 /dev/urandom | /usr/bin/sha512sum | /bin/cut -b 19-50)

generate base32 secret

/bin/echo "... generating base32 secret"
BASE32=$(/usr/bin/oathtool --totp -v ${SECRET}|/bin/grep 'Base32'|/bin/awk '{print $NF}')

generate qrcode

/bin/echo "... generating qrcode"
/usr/bin/qrencode -l H -v 1 --background=FFFFFF -o ${ME}_oath.png "otpauth://totp/${ME}@${HOST}?secret=${BASE32}"

insert secret in oath database

/bin/echo "... adding secret to oath database"
/bin/echo "... adding user to otpuser group"

TMPFILE=$(/bin/mktemp ) || exit 1
/bin/echo -e "HOTP/T30/6\t${ME}\t-\t${SECRET}" > $TMPFILE
/usr/bin/sudo -u root /usr/local/sbin/add_secret.sh ${TMPFILE} ${OTPGROUP} ${ME}
/bin/rm -f TMPFILE

/bin/echo "... finished"
echo "Secret: ${SECRET}
BASE32 Secret:${BASE32}" > ${ME}_oath.dat

/bin/echo "
Your Secret is: ${SECRET}
Your BASE32 Secret is ${BASE32}
Your QR-Code is: ${ME}_oath.png

Enter your secret in your OTP Token (enter BASE32 without the trailing '=')
Display this file and scan it with your OTP Token APP. (X11Forward only)
/bin/echo "To display your QR-Code, press "
read INPUT
if [ "$INPUT" = "d" ]; then
/usr/bin/display ${ME}_oath.png


* Then add oath code into *usersfile*.

*WARNING: The below script that I copied from Internet got syntax error, and I didn't test it as well.*



RRZK, 2015-12-10 (CO)



/bin/cat ${TMPFILE} >> ${OATH_FILE}
/usr/sbin/usermod -a -G ${OTPGROUP} ${USER}
exit 0

## References

[Two-factor time based (TOTP) SSH authentication with pam_oath and Google Authenticator](https://spod.cx/blog/two-factor-ssh-auth-with-pam_oath-google-authenticator.shtml)
[How to Create QR Codes From the Linux Command Line](https://www.cloudsavvyit.com/8382/how-to-create-qr-codes-from-the-linux-command-line/)
[How to generate a QR Code for Google Authenticator that correctly shows Issuer displayed above the OTP?](https://stackoverflow.com/questions/34520928/how-to-generate-a-qr-code-for-google-authenticator-that-correctly-shows-issuer-d)
[Enable user to login to webui](https://www.truenas.com/community/threads/unable-to-login-to-gui-with-non-admin-root-user.19921/)
[Two-Factor Authentication with OTP (Admin Guide)](https://hpc-wiki.info/hpc/Admin_Guide_Two-Factor_Authentication_with_OTP)
[sshd: How to enable PAM authentication for specific users under](https://serverfault.com/questions/222637/sshd-how-to-enable-pam-authentication-for-specific-users-under)

Enable 2FA for Ubuntu

Enable 2FA for Ubuntu


Note: Do not logout from system before testing completed

  • Installing the Google Authenticator PAM module
sudo apt install libpam-google-authenticator
  • Configuring SSH

Add the following line at end of /etc/pam.d/sshd file

auth required pam_google_authenticator.so
  • Enable Challenge Response Authentication

Modify /etc/ssh/sshd_config

ChallengeResponseAuthentication yes
  • Disable password authentication

Modify /etc/ssh/sshd_config

PasswordAuthentication no
  • Restart the sshd daemon
sudo systemctl restart sshd.service

Configuring authentication for user

In a terminal, run following command:


Anwser using recommended configuration:

Make tokens “time-base””: yes
Update the .google_authenticator file: yes
Disallow multiple uses: yes
Increase the original generation time limit: no
Enable rate-limiting: yes

Use Authy scan QR code and save it.


  • Disable user authorized_keys using root account
cd ~user
mv .ssh/authorized_keys .ssh/authorized_
  • Connect as the user using SSH

Note: Use Authy generate Verification code.

ssh host.example.com
Verification code: 
Welcome to Ubuntu 20.04.3 LTS (GNU/Linux 5.4.0-90-generic x86_64)
  • Enable authorized_keys
mv .ssh/authorized_ .ssh/authorized_keys
  • Exit
  • Connect as the user again using SSH
$ ssh host.example.com
Welcome to Ubuntu 20.04.3 LTS (GNU/Linux 5.4.0-90-generic x86_64)
  • Test sudo
$ sudo -i
[sudo] password for user:


  • Disable SSH PasswordAuthentication is not effected, password is still required.

  • Enable public key authentication using authorized_keys will disable 2FA key, this is good for service account

  • Do not configure sudo, /etc/pam.d/sudo is not modified, especially when using it for none password execution, such as running in services.

  • Console access will not using 2FA, because this confiugration is for SSH.


Configure SSH to use two-factor authentication
How To Set Up Multi-Factor Authentication for SSH on Ubuntu 20.04
Note: This was not successful, the document is wrong at following point. I think the second publickey should not be there

AuthenticationMethods publickey,password publickey,keyboard-interactive

2FA App – Authy

2FA App - Authy

There are many 2FA Apps, Microsoft, Google, Duo, etc. But I select Authy.


As an end user, I'm not the one looking at how secure a 2FA App is, it is only generating a code as expected. But I need to two major considerations as my experiences.

  • Backup - My phone was broken, then I lost all my codes, I don't even remember what they are. Very sad experience.

    Yes, Authy backs up data to their own server.

  • Multiple Devices - To make sure my codes won't be lost, then they should be available via multiple locations.

    Yes, Authy can be used in many devices, and can track them in devices list.

  • Offline - To make sure I got my own copy on my hand, I need it works offline.

    Yes, Authy has a local copy.

  • Acceptable by others - When you hear supported by Google Authenticator, it should work.

    Yes, it supports standard TOTP.


  • Don't know how to remove the code from iOS App
  • There is a Default device in devices list, which is quite confusing.
  • How to save backup codes? No solution given.


Easy, 2FA for Any Account
Download Authy
8 Best Two-Factor Authentication Plugins for WordPress
Deprecating Authy for WordPress
Authy Lists an Unknown or Unrecognized Device as "Default"