TrueNAS SCALETrueNAS SCALE Documentation Archive
This content follows the TrueNAS SCALE 22.12 (Bluefin) releases. Archival documentation is provided for reference only and not actively maintained.
Use the Product and Version selectors above to view content specific to different TrueNAS software or major version.

Two_Factor

The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!

Two_Factor Commands

The two_factor namespace has five commands and is based on functions found in the SCALE API and web UI. It provides access to two-factor authentication (2FA) configuration methods through the five two_factor commands.

Config Command

The config command displays current 2FA settings.

Description

The config command does not require entering properties or arguments. Enter the command, then press Enter. The command returns a table showing current 2FA settings.

Usage

From the CLI prompt, enter:

auth two_factor config

auth two_factor config
+------------+--------+
|         id | 1      |
| otp_digits | 6      |
|     secret | <null> |
|     window | 0      |
|   interval | 30     |
|   services | <dict> |
|    enabled | false  |
+------------+--------+

Provisioning_URI Command

The provisioning_uri command displays the provisioning URI for the One-Time Password (OTP).

The provisioning_uri command only displays part of the provisioning URI. For the full URI, access the TrueNAS web UI and go to Credentials > 2FA.

Description

The provisioning_uri command does not require entering properties or arguments. Enter the command, then press Enter. The command returns the OTP provisioning URI for authenticator app QR encoding.

Usage

From the CLI prompt, enter:

auth two_factor provisioning_uri

auth two_factor provisioning_uri
otpauth://totp/mysystems:truenas%50TrueNAS?secret=Noni&is...

Renew_Secret Command

The renew_secret command generates a new secret for 2FA.

Description

The renew_secret command does not require entering properties or arguments. Enter the command, then press Enter. The command returns true when successful, but displays an error if run when 2FA is not enabled.

Usage

From the CLI prompt, enter:

auth two_factor renew_secret

auth two_factor renew_secret
true

Update Command

The update command updates 2FA settings and requires one of five arguments in the command string: enabled, otp_digits, window, interval, and services.

Description

The update enabled command requires you to include either the true (enable) or false (disable) option. Enter the command string, then press Enter. The command returns nothing when successful.

Usage

From the CLI prompt, enter:

auth two_factor update enable=true/false

Where:

  • Where true enables two-factor authentication, and false disables it.
auth two_factor update enabled=true

Description

The update otp_digits command requires you to include a number from six to eight. Enter the command string, then press Enter. The command returns nothing when successful, and returns an error when you enter an invalid integer.

Usage

From the CLI prompt, enter:

auth two_factor update otp_digits=number

Where:

  • number is the number of digits from six to eight.
auth two_factor update otp_digits=6

Description

The update window command extends the validity of one-time passwords and requires you to include an integer. Enter the command string, then press Enter. The command returns nothing when successful, and returns an error when you enter an invalid integer.

Usage

From the CLI prompt, enter:

auth two_factor update window=number

Where:

  • number is the number of passwords before and after the current one that are still valid. Must be between 0 and 999999999999999999.
auth two_factor update window=1

Description

The update interval command sets the lifespans of one-time passwords and requires you to include an integer. Enter the command string, then press Enter. The command returns nothing when successful, and returns an error when you enter an invalid integer.

Usage

From the CLI prompt, enter:

auth two_factor update interval=number

Where:

  • number is the number (in seconds) an OTP will last before expiring. Must be between 5 and 999999999999999999.

s

auth two_factor update interval=30

Description

The update services command enables or disables 2FA for SSH logins, and requires you to include an argument. Enter the command string, then press Enter. The command returns nothing when successful.

Usage

From the CLI prompt, enter:

auth two_factor update services={“ssh”:true/false

Where:

  • true/false enables (true) or disables (false) SSH 2FA authentication.
auth two_factor update services={"ssh":true}

Verify Command

The verify command verifies whether or not a password is authenticated.

Description

The verify command requires the token property. The property argument is separated by the = delimiter. Enter the command, then press Enter. The command returns true if provided token successfully authenticates.

Usage

From the CLI prompt, enter:

auth two_factor verify token=password

Where:

  • password is a TrueNAS user password.
auth two_factor verify token=abcd1234
true

Related CLI Auth Articles