Edit page
TrueNAS SCALETrueCommand Nightly Development Documentation
This content follows experimental early release software. Use the Product and Version selectors above to view content specific to a stable software release.

Completing the Initial Configuration

TrueCommand allows you to manage all your TrueNAS systems from one location. This multi-system management increases efficiency and simplifes operations.

Getting Started

After creating the adminstrator account the first time you log into TrueCommand, you can get started with the initial TrueCommand configuration:

  1. Configure TrueCommand Settings (described in this article).
  2. Connect your first TrueNAS system.
  3. Create user accounts.
  4. Review the Interface Overview article to become familiar with the interface dashboards, toolbars and icons, and navigation.

TrueCommand Administration Screen

The Administration screen, available to users with administrator permissions, displays additional system details and offers a variety of TrueCommand configuration options through the system widgets or information cards.

To access the Administration screen, click the gear icon at the top right of the screen to open the settings menu, then click Administration.

AdministrationScreen

The screen has seven widgets:

  • About - Shows TrueCommand system information, iXsystems Support Contact information, and TrueCommand licenses.
  • Certificates - Allows you to upload or reset certificates.
  • Certificate Authorities - Allows you import certificate authorities into TrueCommand.
  • Configuration - Provides access to general, SSL, alert, LDAP and SAML service, and Telemetry settings.
  • LDAP Servers - Allows you to add an LDAP server.
  • LDAP Teams - Allows you to join LDAP teams.
  • Alert Recipients - Allows you to configure alert recipient users emails and configure mailing list email settings.

About Widget

The About widget displays the current TrueCommand system ID and version, iXsystems Support contact information, and license details.

AdministrationAboutWidget

Click View Open Source Licenses to see a list of open-source licenses TrueCommand uses.

OpenSourceLicensesWindow

Updating Licenses

You can expand TrueCommand to monitor more disks by upgrading or purchasing a license from iXsystems. Click GET A LICENSE to open a new browser tab to purchase a TrueCommand license. You can also contact iXsystems to upgrade the current license.

After you upgrade or purchase a new license, upload it to TrueCommand. Click Browse to open a file browser on your local system. Select the new license file to upload and click UPLOAD LICENSE to apply the new license to TrueCommand.

Certificates Widget

The Certificates widget shows the certificates TrueCommand uses and has options to reset or upload a certificate.

AdministrationCertificatesWidget

Click Upload Certificate to open the Upload Certificate screen, where you can either browse to or drag and drop a certificate and a private key file into TrueCommand.

AdministrationCertificates

Selecting Plain text allows you to copy and paste the raw text instead of uploading a file.

Certificate Authorities Widget

Click IMPORT in the Certificate Authorities widget to add a certificate authority (CA) to TrueCommand.

AdministrationCertificateAuthoritiesWidget

Click Import to open the Add Certificate Authority screen, where you enter the name for the CA and either browse to or drag and drop the CA file into TrueCommand.

AdministrationCAs

Selecting Plain Text allows you to copy and paste the raw text before you upload it.

Configuration Widget

The Configuration widget displays current general, SSL, alert options, LDAP, SAML, and telemetry service settings. It provides access to a configuration screen to add or make changes to these settings:

AdministrationConfigurationWidget

Click CONFIGURE to open the Configuration screen where you can manage feature settings. After changing any options, click Save or Cancel to reset fields back to their previous values.

General Options

General options include settings for account sessions, how long TrueCommand stores system statistics and the number of TrueNAS configuration file backups to store.

ConfigurationScreenGeneralSSLAlertOptions

By default, TrueCommand logs out idle user account sessions after 30 minutes of inactivity. A warning shows when the session is within 3 minutes of timing out. Update the Minutes field to set a different number of minutes before an idle user account is automatically logged out. Setting 0 disables automatic logouts.

TrueCommand stores 3 months of statistics from connected TrueNAS systems and 7 days of TrueNAS database backups. Enter numeric values in the Months and Backups fields to change these defaults.

SSL options

This feature is only available for local installations or containerized TrueCommand deployments.

By default, TrueCommand attempts an SSL connection, then a non-SSL connection if the first attempt fails. You can disable non-SSL connection attempts by setting Require SSL for all connections, which is useful when a monitored system uses a custom port or does not allow SSL-secured access.

There are additional options to configure how TrueCommand handles certificates. By default, TrueCommand accepts self-signed certificates and certificate host name mismatches. Self-signed certificates enable the first-time login to TrueCommand. Accept certificate even if there is a hostname mismatch allows TrueCommand to accept certificates from systems that use a host name, even though it registered them with an IP address (or vice-versa).

ConfigurationScreenSSLOptions

Alert Options

You can adjust the alert levels that TrueCommand shows from a connected TrueNAS system to tune the system messages displayed according to your use case. Select an alert category to ignore. Options are None, Information, Warning and Critical. Alerts generated by TrueCommand rules are unaffected.

LDAP and SAML Options

The Allow LDAP user creation checkbox is not selected (disabled) by default. When disabled, you can use LDAP to log in with existing users.

AdministrationConfigLDAP

The SAML service is an experimental feature that allows users to configure TrueCommand SAML for Active Directory or Google Admin.

Telemetry

TrueCommand reports some anonymous basic usage telemetry to iXsystems for product improvement analysis.

AdministrationConfigTelemetry

Click the PREVIEW button to see what your system is sending.

Select Disable Telemetry to deny telemetry collection.

LDAP Servers Widget

Users can configure TrueCommand to use LDAP servers for security and authentication management among connected TrueNAS systems.

TrueCommand supports using LDAP to better integrate within an established network environment. LDAP/AD allows using single sign-on credentials from the Lightweight Directory Access Protocol (LDAP) or Active Directory (AD). Users can log in with an LDAP or AD account without creating a separate TrueCommand login.

LDAP and AD require the server IP address or DNS hostname and domain to use. The LDAP or AD Username (optional) is required when the TrueCommand user name does not match the LDAP or AD credentials.

Click on the  (Gear) > Administration.
Click Add on the LDAP Servers widget to open the Add LDAP Server configuration screen.

AdministrationLDAPServersWidget

To configure LDAP, type the LDAP server IP address or DNS host name into the LDAP Server URL field, type the domain name in the Domain field, and click ADD SERVER. You can add multiple LDAP servers and domains.

Click on the Test LDAP Config icon to open a window that allows you to test your connection to the LDAP server. The Remove LDAP Server icon removes the selected LDAP server.

AddLDAPServerScreen

LDAP Server Settings
SettingDescription
Hostname(Required) Enter the host name, IP or DNS name, of the LDAP server, with port number on the end. For example: ldap.mycorp.com:636 (SSL port is typically 636 for AD/LDAP).
Domain(Required) Base domain settings of the user. For example: dc=mycorp,dc=com for a typical username@mycorp.com user account.
Group DomainEnter the alternative domain setting to use when searching for groups. The default value is the same as Domain.
Verify SSLSelect to require strict SSL certificate verification. The default value is false. Disable this option if the system host name is not the one on the SSL certificate, the system uses an IP to connect instead of the DNS host name, or the LDAP server uses a self-signed certificate.
User ID FieldEnter the user ID for the user that logs in (this is class-matched to the login username). Enter Domain name to use for user-matching. The default value is uid (user ID). Another commonly-used field is cn (common name).
Group ID FieldEnter the class for finding groups associated with a user. The default is cn (common name). Enter the Domain name to use when searching for a group name.
BIND User DomainEnter the full domain setting for a pre-authenticated bind to the server. For example: uid=binduser,cn=read-only-bind,dc=mycorp,dc=com. For an unauthenticated bind, enter just a name (example: truecommand-bin). This is sometimes used for logging purposes on the LDAP but otherwise is not validated.
RealmEnter the realm that performs authentication against the LDAP server.
BIND PasswordEnter the password to use for the bind user. For an unauthenticated bind, leave blank while setting the BIND User Domain to a non-empty value.
KDCEnter the key distribution center (KDC) that supplies session tickets and temporary session keys to users and computers within the LDAP server.

LDAP connection options

TrueCommand supports two methods of validating LDAP user credentials:

Direct Bind

The direct BIND method uses the Domain and User ID Field values to create a static domain string for user authentication.

Example:

  • Domain: dc=mycorp,dc=com
  • User ID Field: uid

When bobby.singer attempts to log in, TrueCommand establishes an SSL-secure connection to the LDAP server and attempts to bind with the static domain uid=bobby.singer,dc=mycorp,dc=com and the user-provided password. If successful, the user authentication verifies, and Bobby Singer may access TrueCommand.

Indirect Bind

The indirect BIND authentication method is more dynamic and searches for the proper user domain settings rather than making format assumptions. With TrueCommand, indirect BIND configures a bind user (typically a read-only, minimal-permissions user account) with a known domain/password to perform the initial bind to the LDAP server. After logging in, TrueCommand searches for the user domain requesting to log in. It then attempts a second bind with the user domain and provided password.

Example:

  • Domain: dc=mycorp,dc=com
  • User ID Field: uid
  • BIND User Domain: uid=binduser,cn=read-only-bind,dc=mycorp,dc=com
  • BIND Password: pre-shared-key

When bobby.singer attempts to log in, TrueCommand establishes an SSL-secure connection to the LDAP server. TrueCommand uses the BIND User Domain and BIND Password settings to perform an initial bind using pre-known settings from your LDAP provider. When bound, TrueCommand searches for the user matching uid=bobby.singer, but only within the subdomains that include the domain setting (dc=mycorp,dc=com in this example). If TrueCommand finds a user, it uses the entire user domain string from the search result to initialize a second bind along with the user-provided password. If successful, TrueCommand verifies the user authentication, and Bobby Singer is allowed access to TrueCommand.

SSL/TLS Connection Info

AD/LDAP authentication requires SSL connections.
If the LDAP server uses an SSL certificate generated by a custom certificate authority (CA), then one of two things must occur before TrueCommand can use the LDAP server. Either:

  • Users must register the custom certificate authority with TrueCommand via the Certificates tab on the Administration screen.

    Or

  • Users can disable the Verify SSL option to accept whatever SSL certificate the server provides. Users might need to choose this if the LDAP server host name differs from the one listed on the certificate or if the server uses a self-signed SSL certificate.

Selecting Allow LDAP user creation means TrueCommand creates user accounts when someone logs in to the User Interface with their LDAP credentials. JOIN TEAM automatically adds LDAP users to specific TrueCommand teams.

LDAP Teams Widget

The LDAP Teams widget allows you to add TrueCommand teams to your LDAP server by clicking JOIN and selecting a team from the list.

Alert Recipients Widget

The Alert Recipients widget allows you to add recipient email addresses and configure mail list settings.

AdministrationAlertRecipientsWidget

Click Add to open the Add Recipient screen, where you can add an email address to your LDAP server.

AddRecipientScreene

Click Configure to open the Mailing List Configure screen.

MailingListConfigureScreen

Alert Mail List Settings
SettingDescription
MailserverEnter the address for the SMTP server.
Mailserver portEnter the port number the SMTP server listens to.
Auth userEnter the user name for plain authentication.
Auth passEnter the password for plain authentication. Leave blank for no-auth.
FromEnter the email address of the sender.
TlsInitiates a connection with TLS. Uses system settings.