TrueNAS 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 versions.

Group

9 minute read.

Last Modified 2024-03-19 08:47 EDT

The TrueNAS CLI guide for SCALE 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!

Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!

The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.

The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API. For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.

Group Namespace

The group namespace contains eight commands and is based on functions found in the SCALE API and web UI. It provides access to group account creation, configuration, and management.

User Commands

The following group namespace commands allow you to manage groups.

You can enter commands from the main CLI prompt or from the system namespace prompt.

Interactive Argument Editor (TUI)

Create Command

The create command creates a new group.

Using the Create Command

Description

create has seven configuration properties. They are gid, name, smb, sudo_commands, sudo_commands_nopasswd, allow_duplicate_gid, and users. The only required property is name. If a group identification number is not provided, it is automatically filled with the next one available. For more details, see Create Configuration Properties.

Enter the command, then press Enter. The command returns a blank line.

To confirm the group is created, use get_group_obj or go to Credentials > Local Groups in the SCALE Web UI.

Usage

From the CLI prompt, enter:

account group create name=name

Press Enter

From the account prompt, enter:

group create name=name

Press Enter

Where name is the desired group name.

Command Example

account group create name=TestGroup gid=3022 smb=false users=[3000,3001]

Where 3022 is the group id number, TestGroup is the group name, false is a boolean value, and 3000,3001 are user id numbers for group members.

Create Configuration Properties

create has one required and six optional properties for group configuration. name is required. The optional properties are gid, smb, sudo_commands, sudo_commands_nopasswd, allow_duplicate_gid, and users. Property arguments use the = delimiter to separate the property and value. For example, gid=3000. See the table below for details.

Property Functions and Examples

Property	Accepts	Required	Function
`gid`	Integer	No	Assigns the group identification number. If `gid` is not provided it is automatically filled with the next one available. Ex. `gid=3005` Where 3005 is an available GID number.
`name`	String	Yes	Sets the group name. Ex. `name=TestGroup` Where TestGroup is the desired group name.
`smb`	Boolean	No	Sets whether the group should be mapped into an NT group for Windows SMB sharing. Defaults to `true`. Ex. `smb=false` Where false is a boolean value.
`sudo_commands`	Array	No	Sets any sudo commands group members are allowed to use. Security best practice is to limit sudo permissions to administrative users. Ex. `sudo_commands="path1,path2"` Where `path1` and `path2` are absolute paths to the location of executable scripts or packages. You can also use `sudo_commands="ALL"`
`sudo_commands_nopasswd`	Array	No	Sets any sudo commands group members are allowed to use without entering a password. Exercise caution when allowing sudo commands without password prompts. It is recommended to limit this privilege to trusted users and specific commands to minimize security risks. Ex. `sudo_commands_nopasswd="path1,path2"` Where `path1` and `path2` are absolute paths to the location of executable scripts or packages. You can also use `sudo_commands_nopasswd="ALL"`, but this is not recommended.
`allow_duplicate_gid`	Boolean	No	If set to true, allows distinct group names to share the same group identification number. Defaults to false. Important: Use only if absolutely necessary. Duplicate GIDs can lead to unexpected behavior. Ex. `allow_duplicate_gid=true` Where true is a boolean value.
`users`	Array or Integer	No	Assigns users to the group with a list of one or more user identification numbers (UIDs). Ex. `users=[3001,3002]` Where 3001 and 3002 are UID numbers for group members.

Delete Command

The delete command erases an existing group.

Using the Delete Command

Description

If the delete_group option is set to true, the command also deletes any user with the target as its primary group. delete_group defaults to false.

The command returns a blank line.

To confirm the group is deleted, use get_group_obj or navigate to Credentials > Local Groups in the SCALE Web UI.

Usage

From the CLI prompt, enter:

account group delete id=3000

Press Enter.

From the account prompt, enter:

group delete id=3000

Press Enter.

Command Example

account group delete id=3000 options={"delete_group": true}

Where 3000 is the group identification number and true is a boolean value.

options={"delete_group": true} deletes any users whose primary group matches the deleted group. Carefully consider affected users before adding this option.

Get_Group_Obj Command

The get_group_obj command returns dictionary containing information from struct grp including group name, identification number, and group members.

Using the Get_Group_Obj Command

Description

The target group can be specified by group name or GID.

The command returns a list of basic information about the group.

Usage

From the CLI prompt, enter:

account group get_group_obj get_group_obj={“groupname”: “TestGroup”}

Press Enter.

From the account prompt, enter:

group get_group_obj get_group_obj={“groupname”: “TestGroup”}

Press Enter.

Where TestGroup is the name of the target group.

Command Example


account group get_group_obj get_group_obj={"groupname": "TestGroup"}
+---------+------------+
| gr_name | TestGroup  |
|  gr_gid | 3002       |
|  gr_mem | testuser   |
|         | AttTest    |
+---------+------------+

The target group can also be specified by group identification number.

Command Example


account group get_group_obj get_group_obj={"gid": 3002}
+---------+------------+
| gr_name | TestGroup  |
|  gr_gid | 3002       |
|  gr_mem | testuser   |
|         | AttTest    |
+---------+------------+

Where 3002 is the GID number for the target group.

Get_Instance Command

The TrueNAS CLI guide for SCALE is a work in progress! Full documentation for this command is still being developed. Check back for updated information.

The get_instance command retrieves information about a group.

Get_Next_Gid Command

The get_next_gid command displays the next available group identification (GID) number.

Using the get_next_gid Command

Description

get_next_gid returns the next available GID in numerical order. Default behavior begins identification number for local groups at 3000.

Usage

From the CLI prompt, enter:

account group get_next_gid

Press Enter

From the account prompt, enter:

group get_next_gid

Press Enter

Command Example

account group get_next_gid
3000

Has_Password_Enabled_User Command

The has_password_enabled_user command checks whether at least one local user with a password enabled is a member of one or more provided groups.

Using the Has_Password_Enabled_User Command

Description

Target groups are specified by group identification number (GID). Returns a single boolean value for all targeted groups.

The exclude_user_ids option sets specified password enabled users to ignore.

has_password_enabled_user returns a single boolean value for the entire list of GIDs queried. If more than one group is included in the query, the command does not return group specific information.

Usage

From the CLI prompt, enter:

account group has_password_enabled_user gids=3001

Press Enter

From the account prompt, enter:

group has_password_enabled_user gids=3001

Press Enter

Where 3001 represents the GID(s) to query.

Command Examples


account group has_password_enabled_user gids=3001
false


account group has_password_enabled_user gids=3002
true


account group has_password_enabled_user gids=3001,3002
true

Query Command

The TrueNAS CLI guide for SCALE is a work in progress! Full documentation for this command is still being developed. Check back for updated information.

The query command retrieves information about a group or groups and can use various query-filters and query-options.

Using the Query Command

Description

Enter the command with no additional attributes or properties to perform a basic query of all local groups.

Add additional properties to return the value of the specified key(s) for all groups. There are 13 query properties available.

Query Properties

Property	Purpose
`gid`
`name`
`smb`
`sudo_commands`
`sudo_commands_nopasswd`
`users`
`id`
`group`
`builtin`
`id_type_both`
`local`
`nt_name`
`sid`

Expanded information may be requested by specifying the extra option "extra": {"additional_information": []}.

There are two additional_information options supported.

Option	Purpose
`SMB`	Includes Windows SID and NT Name for group. If this option is not specified, then these keys have `null` value.
`DS`	Includes groups from Directory Service (LDAP or Active Directory) in results

Usage

From the CLI prompt, enter:

account group query

Press Enter

From the account prompt, enter:

group query

Press Enter

Command Example

account group query
+-------+------------------------+---------+---------------+------------------------+-------+------------------+-------+--------------+---------+--------+
| gid   | name                   | builtin | sudo_commands | sudo_commands_nopasswd | smb   | users            | local | id_type_both | nt_name | sid    |
+-------+------------------------+---------+---------------+------------------------+-------+------------------+-------+--------------+---------+--------+
| 0     | wheel                  | true    | <empty list>  | <empty list>           | false | root             | true  | false        | <null>  | <null> |
| 1     | daemon                 | true    | <empty list>  | <empty list>           | false | daemon           | true  | false        | <null>  | <null> |
| 15    | kmem                   | true    | <empty list>  | <empty list>           | false | <empty list>     | true  | false        | <null>  | <null> |
| 3     | sys                    | true    | <empty list>  | <empty list>           | false | sys              | true  | false        | <null>  | <null> |
| 5     | tty                    | true    | <empty list>  | <empty list>           | false | <empty list>     | true  | false        | <null>  | <null> |
| 37    | operator               | true    | <empty list>  | <empty list>           | false | uucp             | true  | false        | <null>  | <null> |
| 8     | mail                   | true    | <empty list>  | <empty list>           | false | mail             | true  | false        | <null>  | <null> |
| 2     | bin                    | true    | <empty list>  | <empty list>           | false | bin              | true  | false        | <null>  | <null> |
| 9     | news                   | true    | <empty list>  | <empty list>           | false | news             | true  | false        | <null>  | <null> |
...

Additional properties included in the command string return specific information.

Command Example

account group query gid
+-------+
| gid   |
+-------+
| 0     |
| 1     |
| 15    |
| 3     |
| 5     |
| 37    |
| 8     |
| 2     |
| 9     |
...

query can also return information about a specific group.

Update Command

The update command updates the attributes of an existing group. For available properties, see Create Configuration Properties.

Using the Update Command

Descripton

Syntax and available properties for update closely follow those of create.

The command returns a blank line.

To confirm the group is updated, use get_group_obj or navigate to Credentials > Local Groups in the SCALE Web UI.

Usage

From the CLI prompt, enter:

account group update gid_or_name=3006 users=3001

From the account prompt, enter:

group update

Where 3006 is the identification number or GID for the target group and users=3001 represents the property(s) to update.

Command Example

account group update gid_or_name=3006 users=3001

The command as written adds the user with UID 3001 to the group with GID 3006.

Group

Group Namespace

User Commands

Interactive Argument Editor (TUI)

Create Command

Description

Usage

Create Configuration Properties

Delete Command

Description

Usage

Get_Group_Obj Command

Description

Usage

Get_Instance Command

Get_Next_Gid Command

Description

Usage

Has_Password_Enabled_User Command

Description

Usage

Query Command

Description

Usage

Update Command

Descripton

Usage

Related CLI Account Articles

Related SCALE Groups Articles