# user.query

Sent on user changes.

Type: object

##

#### UserAddedEvent

Type: object
No Additional Properties

##

#### Id

Type: integer

##

#### UserEntry

Type: object
No Additional Properties

##

#### Id

Type: integer

This is the API identifier for the user. Use this ID for `user.update` and `user.delete` API calls. This ID also appears in the `users` array for each group entry in `group.query` results.

NOTE: For users from a directory service, the `id` is calculated by adding 100000000 to the `uid`. This ensures consistent API results. You cannot change directory service accounts through TrueNAS.

##

#### Uid

Type: integer

A non-negative integer used to identify a system user. TrueNAS uses this value for permission checks and many other system purposes.

##

#### Username

A string used to identify a user. Local accounts must use characters from the POSIX portable filename character set.

## Any of

Type: string
Type: string

Must be at least `1` characters long

##

#### Unixhash

Hashed password for local accounts. This value is `null` for accounts provided by directory services.

## Any of

Type: string
Type: null

##

#### Smbhash

NT hash of the local account password for `smb` users. This value is `null` for accounts provided by directory services or non-SMB accounts.

## Any of

Type: string
Type: null

##

#### Home

Type: string Default: "/var/empty"

The local file system path for the user account's home directory.
Typically, this is required only if the account has shell access (local or SSH) to TrueNAS.
This is not required for accounts used only for SMB share access.

Must be at least `1` characters long

##

#### Shell

Type: string Default: "/usr/bin/zsh"

Available choices can be retrieved with `user.shell_choices`.

Must be at least `1` characters long

##

#### Full Name

Type: string

Comment field to provide additional information about the user account. Typically, this is the full name of the user or a short description of a service account. There are no character set restrictions for this field. This field is for information only.

##

#### Builtin

Type: boolean

If `true`, the user account is an internal system account for the TrueNAS server. Typically, one should create dedicated user accounts for access to the TrueNAS server webui and shares.

##

#### Smb

Type: boolean Default: true

The user account may be used to access SMB shares. If set to `true` then TrueNAS stores an NT hash of the user account's password for local accounts. This feature is unavailable for local accounts when General Purpose OS STIG compatibility mode is enabled. If set to `true` the user is automatically added to the `builtin_users` group.

##

#### Userns Idmap

Default: null

Specifies the subuid mapping for this user. If DIRECT then the UID will be directly mapped to all containers. Alternatively, the target UID may be explicitly specified. If `null`, then the UID will not be mapped.

NOTE: This field will be ignored for users that have been assigned TrueNAS roles.

## Any of

Type: enum (of null or string)

##### Must be one of:

- "DIRECT"
- null

Type: integer

Value must be greater or equal to `1` and lesser or equal to `4294967294`

##

#### Group

Type: object

The primary group of the user account.

##

#### Groups

Type: array of integer

Array of additional groups to which the user belongs. NOTE: Groups are identified by their group entry `id`, not their Unix group ID (`gid`).

No Additional Items

##### Each item of this array must be:

Type: integer

##

#### Password Disabled

Type: boolean Default: false

If set to `true` password authentication for the user account is disabled.

NOTE: Users with password authentication disabled may still authenticate to the TrueNAS server by other methods, such as SSH key-based authentication.

NOTE: Password authentication is required for `smb` users.

##

#### Ssh Password Enabled

Type: boolean Default: false

Allow the user to authenticate to the TrueNAS SSH server using a password.

WARNING: The established best practice is to use only key-based authentication for SSH servers.

##

#### Sshpubkey

Default: null

SSH public keys corresponding to private keys that authenticate this user to the TrueNAS SSH server.

## Any of

Type: string
Type: null

##

#### Locked

Type: boolean Default: false

If set to `true` the account is locked. The account cannot be used to authenticate to the TrueNAS server.

##

#### Sudo Commands

Type: array of string

An array of commands the user may execute with elevated privileges. User is prompted for password when executing any command from the array.

No Additional Items

##### Each item of this array must be:

Type: string

Must be at least `1` characters long

##

#### Sudo Commands Nopasswd

Type: array of string

An array of commands the user may execute with elevated privileges. User is not prompted for password when executing any command from the array.

No Additional Items

##### Each item of this array must be:

Type: string

Must be at least `1` characters long

##

#### Email

Default: null

Email address of the user. If the user has the `FULL_ADMIN` role, they will receive email alerts and notifications.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Local

Type: boolean

If `true`, the account is local to the TrueNAS server. If `false`, the account is provided by a directory service.

##

#### Immutable

Type: boolean

If `true`, the account is system-provided and most fields related to it may not be changed.

##

#### Twofactor Auth Configured

Type: boolean

If `true`, the account has been configured for two-factor authentication. Users are prompted for a second factor when authenticating to the TrueNAS web UI and API. They may also be prompted when signing in to the TrueNAS SSH server using a password (depending on global two-factor authentication settings).

##

#### Sid

The Security Identifier (SID) of the user if the account an `smb` account. The SMB server uses this value to check share access and for other purposes.

## Any of

Type: string
Type: null

##

#### Last Password Change

The date of the last password change for local user accounts.

## Any of

Type: string Format: date-time
Type: null

##

#### Password Age

The age in days of the password for local user accounts.

## Any of

Type: integer
Type: null

##

#### Password History

This contains hashes of the ten most recent passwords used by local user accounts, and is for enforcing password history requirements as defined in system.security.

## Any of

Type: array
No Additional Items

##### Each item of this array must be:

Type: object
Type: null

##

#### Password Change Required

Type: boolean

Password change for local user account is required on next login.

##

#### Roles

Type: array of string

Array of roles assigned to this user's groups. Roles control administrative access to TrueNAS through the web UI and API.

No Additional Items

##### Each item of this array must be:

Type: string

##

#### Api Keys

Type: array of integer

Array of API key IDs associated with this user account for programmatic access.

No Additional Items

##### Each item of this array must be:

Type: integer

##

#### UserChangedEvent

Type: object
No Additional Properties

##

#### Id

Type: integer

##

#### UserEntry

Type: object
No Additional Properties

##

#### Id

Type: integer

This is the API identifier for the user. Use this ID for `user.update` and `user.delete` API calls. This ID also appears in the `users` array for each group entry in `group.query` results.

NOTE: For users from a directory service, the `id` is calculated by adding 100000000 to the `uid`. This ensures consistent API results. You cannot change directory service accounts through TrueNAS.

##

#### Uid

Type: integer

A non-negative integer used to identify a system user. TrueNAS uses this value for permission checks and many other system purposes.

##

#### Username

A string used to identify a user. Local accounts must use characters from the POSIX portable filename character set.

## Any of

Type: string
Type: string

Must be at least `1` characters long

##

#### Unixhash

Hashed password for local accounts. This value is `null` for accounts provided by directory services.

## Any of

Type: string
Type: null

##

#### Smbhash

NT hash of the local account password for `smb` users. This value is `null` for accounts provided by directory services or non-SMB accounts.

## Any of

Type: string
Type: null

##

#### Home

Type: string Default: "/var/empty"

The local file system path for the user account's home directory.
Typically, this is required only if the account has shell access (local or SSH) to TrueNAS.
This is not required for accounts used only for SMB share access.

Must be at least `1` characters long

##

#### Shell

Type: string Default: "/usr/bin/zsh"

Available choices can be retrieved with `user.shell_choices`.

Must be at least `1` characters long

##

#### Full Name

Type: string

Comment field to provide additional information about the user account. Typically, this is the full name of the user or a short description of a service account. There are no character set restrictions for this field. This field is for information only.

##

#### Builtin

Type: boolean

If `true`, the user account is an internal system account for the TrueNAS server. Typically, one should create dedicated user accounts for access to the TrueNAS server webui and shares.

##

#### Smb

Type: boolean Default: true

The user account may be used to access SMB shares. If set to `true` then TrueNAS stores an NT hash of the user account's password for local accounts. This feature is unavailable for local accounts when General Purpose OS STIG compatibility mode is enabled. If set to `true` the user is automatically added to the `builtin_users` group.

##

#### Userns Idmap

Default: null

Specifies the subuid mapping for this user. If DIRECT then the UID will be directly mapped to all containers. Alternatively, the target UID may be explicitly specified. If `null`, then the UID will not be mapped.

NOTE: This field will be ignored for users that have been assigned TrueNAS roles.

## Any of

Type: enum (of null or string)

##### Must be one of:

- "DIRECT"
- null

Type: integer

Value must be greater or equal to `1` and lesser or equal to `4294967294`

##

#### Group

Type: object

The primary group of the user account.

##

#### Groups

Type: array of integer

Array of additional groups to which the user belongs. NOTE: Groups are identified by their group entry `id`, not their Unix group ID (`gid`).

No Additional Items

##### Each item of this array must be:

Type: integer

##

#### Password Disabled

Type: boolean Default: false

If set to `true` password authentication for the user account is disabled.

NOTE: Users with password authentication disabled may still authenticate to the TrueNAS server by other methods, such as SSH key-based authentication.

NOTE: Password authentication is required for `smb` users.

##

#### Ssh Password Enabled

Type: boolean Default: false

Allow the user to authenticate to the TrueNAS SSH server using a password.

WARNING: The established best practice is to use only key-based authentication for SSH servers.

##

#### Sshpubkey

Default: null

SSH public keys corresponding to private keys that authenticate this user to the TrueNAS SSH server.

## Any of

Type: string
Type: null

##

#### Locked

Type: boolean Default: false

If set to `true` the account is locked. The account cannot be used to authenticate to the TrueNAS server.

##

#### Sudo Commands

Type: array of string

An array of commands the user may execute with elevated privileges. User is prompted for password when executing any command from the array.

No Additional Items

##### Each item of this array must be:

Type: string

Must be at least `1` characters long

##

#### Sudo Commands Nopasswd

Type: array of string

An array of commands the user may execute with elevated privileges. User is not prompted for password when executing any command from the array.

No Additional Items

##### Each item of this array must be:

Type: string

Must be at least `1` characters long

##

#### Email

Default: null

Email address of the user. If the user has the `FULL_ADMIN` role, they will receive email alerts and notifications.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Local

Type: boolean

If `true`, the account is local to the TrueNAS server. If `false`, the account is provided by a directory service.

##

#### Immutable

Type: boolean

If `true`, the account is system-provided and most fields related to it may not be changed.

##

#### Twofactor Auth Configured

Type: boolean

If `true`, the account has been configured for two-factor authentication. Users are prompted for a second factor when authenticating to the TrueNAS web UI and API. They may also be prompted when signing in to the TrueNAS SSH server using a password (depending on global two-factor authentication settings).

##

#### Sid

The Security Identifier (SID) of the user if the account an `smb` account. The SMB server uses this value to check share access and for other purposes.

## Any of

Type: string
Type: null

##

#### Last Password Change

The date of the last password change for local user accounts.

## Any of

Type: string Format: date-time
Type: null

##

#### Password Age

The age in days of the password for local user accounts.

## Any of

Type: integer
Type: null

##

#### Password History

This contains hashes of the ten most recent passwords used by local user accounts, and is for enforcing password history requirements as defined in system.security.

## Any of

Type: array
No Additional Items

##### Each item of this array must be:

Type: object
Type: null

##

#### Password Change Required

Type: boolean

Password change for local user account is required on next login.

##

#### Roles

Type: array of string

Array of roles assigned to this user's groups. Roles control administrative access to TrueNAS through the web UI and API.

No Additional Items

##### Each item of this array must be:

Type: string

##

#### Api Keys

Type: array of integer

Array of API key IDs associated with this user account for programmatic access.

No Additional Items

##### Each item of this array must be:

Type: integer

##

#### UserRemovedEvent

Type: object
No Additional Properties

##

#### Id

Type: integer

Required roles: ACCOUNT_READ