container.query

Type: object

Type: array
No Additional Items

Tuple Validation

Parameter 1: filters

filters

Type: array Default: []

List of filters for query results. See API documentation for "Query Methods" for more guidance.

 No Additional Items
Each item of this array must be:
Type: object

Examples:

[
    [
        "name",
        "=",
        "bob"
    ]
]

[
    [
        "OR",
        [
            [
                "name",
                "=",
                "bob"
            ],
            [
                "name",
                "=",
                "larry"
            ]
        ]
    ]
]
Parameter 2: options

options

Type: object
Default:
{ "extra": {}, "order_by": [], "select": [], "count": false, "get": false, "offset": 0, "limit": 0, "force_sql_filters": false }

Query options including pagination, ordering, and additional parameters.

 No Additional Properties

Extra

Type: object Default: {}

Extra options are defined on a per-endpoint basis and are described in the documentation for the associated query method.

Order By

Type: array of string Default: []

An array of field names describing the manner in which query results should be ordered. The field names may also have one of more of the following special prefixes: - (reverse sort direction), nulls_first: (place any null values at the head of the results list), nulls_last: (place any null values at the tail of the results list).

No Additional Items
Each item of this array must be:
Type: string

Example:

[
    "size",
    "-devname",
    "nulls_first:-expiretime"
]

Select

Type: array Default: []

An array of field names specifying the exact fields to include in the query return. The dot character . may be used to explicitly select only subkeys of the query result.

No Additional Items
Each item of this array must be:

Type: string
Type: array
No Additional Items
Each item of this array must be:
Type: object

Example:

[
    "username",
    "Authentication.status"
]

Count

Type: boolean Default: false

Return a numeric value representing the number of items that match the specified query-filters.

Get

Type: boolean Default: false

Return the JSON object of the first result matching the specified query-filters. The query fails if there specified query-filters return no results.

Offset

Type: integer Default: 0

This specifies the beginning offset of the results array. When combined with the limit query-option it may be used to implement pagination of large results arrays. WARNING: some query methods provide volatile results and the onus is on the developer to understand whether pagination is appropriate for a particular query API method.

Limit

Type: integer Default: 0

This specifies the maximum number of results matching the specified query-filters to return. When combined wtih the offset query-option it may be used to implement pagination of large results arrays.

WARNING: Some query methods provide volatile results and the onus is on the developer to understand whether pagination is appropriate for a particular query API method.

Force Sql Filters

Type: boolean Default: false

Force use of SQL for result filtering to reduce response time. May not work for all methods.

Result


Type: array of object
No Additional Items
Each item of this array must be:

ContainerQueryResultItem

Type: object
No Additional Properties

Id

Type: integer

Container ID.

Uuid


Container UUID (for libvirt).

Type: string
Type: null

Name

Type: string

Container name.

Must be at least 1 characters long

Description

Type: string

Container description.

Devices

Type: array of object

Container's devices.

 No Additional Items
Each item of this array must be:

ContainerDeviceEntry

Type: object
No Additional Properties

Id

Type: integer

Unique identifier for the containers device.

Attributes


Device-specific configuration attributes.

ContainerFilesystemDevice

Type: object
No Additional Properties

Dtype

Type: const

Device type identifier for FILESYSTEM devices.

Specific value: "FILESYSTEM"

Target

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

Target must not contain braces.

Must match regular expression: ^[^{}]*$

Must be at least 1 characters long

Source

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

Source must not contain braces, and not start with /mnt/.

Must match regular expression: ^[^{}]*$

Must be at least 1 characters long

ContainerGPUDevice

Type: object
No Additional Properties

Dtype

Type: const

Device type identifier for GPU devices.

Specific value: "GPU"

Gpu Type

Type: enum (of string)

GPU device type.

Must be one of:
  • "AMD"
  • "INTEL"
  • "NVIDIA"

Pci Address

Type: string

PCI address of the GPU device on the host system.

Must be at least 1 characters long

ContainerNICDevice

Type: object
No Additional Properties

Dtype

Type: const

Device type identifier for network interface cards.

Specific value: "NIC"

Trust Guest Rx Filters

Type: boolean Default: false

Whether to trust guest OS receive filter settings for better performance.

Type

Type: enum (of string) Default: "E1000"

Network interface controller type. E1000 for Intel compatibility, VIRTIO for performance.

Must be one of:
  • "E1000"
  • "VIRTIO"

Nic Attach

Default: null

Host network interface or bridge to attach to. null for no attachment.

Type: string
Type: null

Mac

Default: null

MAC address for the virtual network interface. null for auto-generation.

Type: string
Must match regular expression: ^([0-9A-Fa-f]{2}[:-]?){5}([0-9A-Fa-f]{2})$
Type: null

ContainerUSBDevice

Type: object
No Additional Properties

Dtype

Type: const

Device type identifier for USB devices.

Specific value: "USB"

Default: null

USB device attributes for identification. null for USB host controller only.

USBAttributes

Type: object
No Additional Properties

Vendor Id

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

USB vendor identifier in hexadecimal format (e.g., '0x1d6b' for Linux Foundation).

Must match regular expression: ^0x.*

Must be at least 1 characters long

Product Id

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

USB product identifier in hexadecimal format (e.g., '0x0002' for 2.0 root hub).

Must match regular expression: ^0x.*

Must be at least 1 characters long

Type: null

Device

Default: null

Host USB device path to pass through. null for controller only.

Type: string

Must be at least 1 characters long

Type: null

Container

Type: integer

ID of the container this device belongs to.

Cpuset


List of physical CPU numbers that domain process and virtual CPUs can be pinned to by default.

Type: string
Type: null

Autostart

Type: boolean

Automatically start the container on boot.

Time

Type: enum (of string)

Whether container time should be local time or UTC time.

Must be one of:
  • "LOCAL"
  • "UTC"

Shutdown Timeout

Type: integer

How many seconds to wait for container to shut down before killing it.

Value must be greater or equal to 5 and lesser or equal to 300

Dataset

Type: string

Which dataset to use as the container root filesystem.

Init

Type: string

"init" process commandline.

Initdir


"init" process working dir.

Type: string
Type: null

Initenv

Type: object

"init" process environment variables.

Each additional property must conform to the following schema

Type: string

Inituser


"init" process username.

Type: string
Type: null

Initgroup


"init" process group.

Type: string
Type: null

Idmap


Idmap configuration for the container There are three two possible values: DEFAULT: This applies the standard TrueNAS idmap namespace configuration. It changes user ID (UID) 0 (root) in the container to UID 2147000001 (truenascontainerunpriv_root). It offsets the other container UIDs by the same amount. For example, UID 1000 in the container becomes UID 2147001001 in the host. ISOLATED: Same as DEFAULT, but UID will be calculated as 2147000001 + 65536 * slice. This will ensure unique ID for each container (provided that the slice is also unique).
None: The container does not apply any idmap namespace. Container UIDs map directly to host UIDs. For example, UID 0 in the container is UID 0 in the host. WARNING: For security, use the DEFAULT value. Security best practice is to run containers with idmap namespaces.


DefaultIdmapConfiguration

Type: object
No Additional Properties

Type

Type: const

Configuration type for default ID mapping.

Specific value: "DEFAULT"

IsolatedIdmapConfiguration

Type: object
No Additional Properties

Type

Type: const

Configuration type for isolated ID mapping.

Specific value: "ISOLATED"

Slice


null when creating means we'll look up an unused slice on backend.

Type: integer

Value must be strictly greater than 0 and strictly lesser than 1000

Type: null
Type: null

Capabilities Policy

Type: enum (of string)

Default rules for capabilities: either keep the default behavior that is dropping the following capabilities: sysmodule, systime, mknod, auditcontrol, macadmin. Or keep all capabilities, or drop all capabilities.

Must be one of:
  • "DEFAULT"
  • "ALLOW"
  • "DENY"

Capabilities State

Type: object

Enable or disable specific capabilities.

Each additional property must conform to the following schema

Type: boolean

Default Network


The default network bridge this container will use when no NIC devices are explicitly attached. When the container has explicitly configured NIC devices, this is null because the NIC configuration is visible in the devices list.

Type: string
Type: null

ContainerStatus

Type: object

Container state.

 No Additional Properties

State

Type: enum (of string)

Container state.

Must be one of:
  • "RUNNING"
  • "STOPPED"

Pid


Container host PID (if running). Informational only do not rely on this value to identify the container's init process.

Type: integer
Type: null

Domain State


Domain state reported by libvirt.

Type: string

Must be at least 1 characters long

Type: null

ContainerQueryResultItem

Type: object
No Additional Properties

Id

Type: integer

Container ID.

Uuid


Container UUID (for libvirt).

Type: string
Type: null

Name

Type: string

Container name.

Must be at least 1 characters long

Description

Type: string

Container description.

Devices

Type: array

Container's devices.

 No Additional Items
Each item of this array must be:
Type: object

Cpuset


List of physical CPU numbers that domain process and virtual CPUs can be pinned to by default.

Type: string
Type: null

Autostart

Type: boolean

Automatically start the container on boot.

Time

Type: enum (of string)

Whether container time should be local time or UTC time.

Must be one of:
  • "LOCAL"
  • "UTC"

Shutdown Timeout

Type: integer

How many seconds to wait for container to shut down before killing it.

Value must be greater or equal to 5 and lesser or equal to 300

Dataset

Type: string

Which dataset to use as the container root filesystem.

Init

Type: string

"init" process commandline.

Initdir


"init" process working dir.

Type: string
Type: null

Initenv

Type: object

"init" process environment variables.

Each additional property must conform to the following schema

Type: string

Inituser


"init" process username.

Type: string
Type: null

Initgroup


"init" process group.

Type: string
Type: null

Idmap


Idmap configuration for the container There are three two possible values: DEFAULT: This applies the standard TrueNAS idmap namespace configuration. It changes user ID (UID) 0 (root) in the container to UID 2147000001 (truenascontainerunpriv_root). It offsets the other container UIDs by the same amount. For example, UID 1000 in the container becomes UID 2147001001 in the host. ISOLATED: Same as DEFAULT, but UID will be calculated as 2147000001 + 65536 * slice. This will ensure unique ID for each container (provided that the slice is also unique).
None: The container does not apply any idmap namespace. Container UIDs map directly to host UIDs. For example, UID 0 in the container is UID 0 in the host. WARNING: For security, use the DEFAULT value. Security best practice is to run containers with idmap namespaces.


Type: object
Type: object
Type: null

Capabilities Policy

Type: enum (of string)

Default rules for capabilities: either keep the default behavior that is dropping the following capabilities: sysmodule, systime, mknod, auditcontrol, macadmin. Or keep all capabilities, or drop all capabilities.

Must be one of:
  • "DEFAULT"
  • "ALLOW"
  • "DENY"

Capabilities State

Type: object

Enable or disable specific capabilities.

Each additional property must conform to the following schema

Type: boolean

Default Network


The default network bridge this container will use when no NIC devices are explicitly attached. When the container has explicitly configured NIC devices, this is null because the NIC configuration is visible in the devices list.

Type: string
Type: null

Type: object

Container state.
Type: integer


Required roles: CONTAINER_READ