Get the schemas for all DNS providers we support for ACME DNS Challenge and the respective attributes required for connecting to them while validating a DNS Challenge
/acme/dns/authenticator/authenticator_schemas
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/acme/dns/authenticator
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete DNS Authenticator of `id`
/acme/dns/authenticator/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/acme/dns/authenticator/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update DNS Authenticator of `id`
/acme/dns/authenticator/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create a DNS Authenticator Create a specific DNS Authenticator containing required authentication details for the said provider to successfully connect with it
/acme/dns/authenticator
| Name | Description |
|---|---|
| body |
Force an update of the AD machine account password. This can be used to refresh the Kerberos principals in the server's system keytab.
/activedirectory/change_trust_account_pw
Returns the following information about the currently joined domain: `LDAP server` IP address of current LDAP server to which TrueNAS is connected. `LDAP server name` DNS name of LDAP server to which TrueNAS is connected `Realm` Kerberos realm `LDAP port` `Server time` timestamp. `KDC server` Kerberos KDC to which TrueNAS is connected `Server time offset` current time offset from DC. `Last machine account password change`. timestamp
/activedirectory/domain_info
| Name | Description |
|---|---|
| body |
/activedirectory
Return list of kerberos SPN entries registered for the server's Active Directory computer account. This may not reflect the state of the server's current kerberos keytab.
/activedirectory/get_spn_list
Wrapper function for 'directoryservices.get_state'. Returns only the state of the Active Directory service.
/activedirectory/get_state
Leave Active Directory domain. This will remove computer object from AD and clear relevant configuration data from the NAS. This requires credentials for appropriately-privileged user. Credentials are used to obtain a kerberos ticket, which is used to perform the actual removal from the domain.
/activedirectory/leave
| Name | Description |
|---|---|
| body |
Returns list of available LDAP schema choices.
/activedirectory/nss_info_choices
Update active directory configuration. `domainname` full DNS domain name of the Active Directory domain. `bindname` username used to perform the intial domain join. `bindpw` password used to perform the initial domain join. User- provided credentials are used to obtain a kerberos ticket, which is used to perform the actual domain join. `verbose_logging` increase logging during the domain join process. `use_default_domain` controls whether domain users and groups have the pre-windows 2000 domain name prepended to the user account. When enabled, the user appears as "administrator" rather than "EXAMPLEdministrator" `allow_trusted_doms` enable support for trusted domains. If this parameter is enabled, then separate idmap backends _must_ be configured for each trusted domain, and the idmap cache should be cleared. `allow_dns_updates` during the domain join process, automatically generate DNS entries in the AD domain for the NAS. If this is disabled, then a domain administrator must manually add appropriate DNS entries for the NAS. This parameter is recommended for TrueNAS HA servers. `disable_freenas_cache` disables active caching of AD users and groups. When disabled, only users cached in winbind's internal cache are visible in GUI dropdowns. Disabling active caching is recommended in environments with a large amount of users. `site` AD site of which the NAS is a member. This parameter is auto- detected during the domain join process. If no AD site is configured for the subnet in which the NAS is configured, then this parameter appears as 'Default-First-Site-Name'. Auto-detection is only performed during the initial domain join. `kerberos_realm` in which the server is located. This parameter is automatically populated during the initial domain join. If the NAS has an AD site configured and that site has multiple kerberos servers, then the kerberos realm is automatically updated with a site-specific configuration to use those servers. Auto-detection is only performed during initial domain join. `kerberos_principal` kerberos principal to use for AD-related operations outside of Samba. After intial domain join, this field is updated with the kerberos principal associated with the AD machine account for the NAS. `nss_info` controls how Winbind retrieves Name Service Information to construct a user's home directory and login shell. This parameter is only effective if the Active Directory Domain Controller supports the Microsoft Services for Unix (SFU) LDAP schema. `timeout` timeout value for winbind-related operations. This value may need to be increased in environments with high latencies for communications with domain controllers or a large number of domain controllers. Lowering the value may cause status checks to fail. `dns_timeout` timeout value for DNS queries during the initial domain join. This value is also set as the NETWORK_TIMEOUT in the ldap config file. `createcomputer` Active Directory Organizational Unit in which new computer accounts are created. The OU string is read from top to bottom without RDNs. Slashes ("/") are used as delimiters, like `Computers/Servers/NAS`. The backslash ("\") is used to escape characters but not as a separator. Backslashes are interpreted at multiple levels and might require doubling or even quadrupling to take effect. When this field is blank, new computer accounts are created in the Active Directory default OU. The Active Directory service is started after a configuration update if the service was initially disabled, and the updated configuration sets `enable` to `True`. The Active Directory service is stopped if `enable` is changed to `False`. If the configuration is updated, but the initial `enable` state is `True`, and remains unchanged, then the samba server is only restarted. During the domain join, a kerberos keytab for the newly-created AD machine account is generated. It is used for all future LDAP / AD interaction and the user-provided credentials are removed.
/activedirectory
| Name | Description |
|---|---|
| body |
Issue a no-effect command to our DC. This checks if our secure channel connection to our domain controller is still alive. It has much less impact than wbinfo -t. Default winbind request timeout is 60 seconds, and can be adjusted by the smb4.conf parameter 'winbind request timeout ='
/activedirectory/started
Dismiss `id` alert.
/alert/dismiss
| Name | Description |
|---|---|
| body |
List all types of alerts which the system can issue.
/alert/list_categories
List all types of alerts including active/dismissed currently in the system.
/alert/list
List all alert policies which indicate the frequency of the alerts.
/alert/list_policies
Restore `id` alert which had been dismissed.
/alert/restore
| Name | Description |
|---|---|
| body |
/alertclasses
Update default Alert settings.
/alertclasses
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/alertservice
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete Alert Service of `id`.
/alertservice/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/alertservice/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update Alert Service of `id`.
/alertservice/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
List all types of supported Alert services which can be configured with the system.
/alertservice/list_types
Create an Alert Service of specified `type`. If `enabled`, it sends alerts to the configured `type` of Alert Service.
/alertservice
| Name | Description |
|---|---|
| body |
Send a test alert using `type` of Alert Service.
/alertservice/test
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/api_key
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete API Key `id`.
/api_key/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/api_key/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update API Key `id`. Specify `reset: true` to reset this API Key.
/api_key/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Creates API Key. `name` is a user-readable name for key.
/api_key
| Name | Description |
|---|---|
| body |
Verify username and password
/auth/check_password
| Name | Description |
|---|---|
| body |
Verify username and password (this will only validate root user's password and would return `false` for any other user)
/auth/check_user
| Name | Description |
|---|---|
| body |
Generate a token to be used for authentication. `ttl` stands for Time To Live, in seconds. The token will be invalidated if the connection has been inactive for a time greater than this. `attrs` is a general purpose object/dictionary to hold information about the token.
/auth/generate_token
| Name | Description |
|---|---|
| body |
Returns list of active auth sessions. Example of return value: [ { "id": "NyhB1J5vjPjIV82yZ6caU12HLA1boDJcZNWuVQM4hQWuiyUWMGZTz2ElDp7Yk87d", "origin": "192.168.0.3:40392", "credentials": "TOKEN", "internal": False, "created_at": {"$date": 1545842426070} } ] `credentials` can be `UNIX_SOCKET`, `ROOT_TCP_SOCKET`, `TRUENAS_NODE`, `LOGIN_PASSWORD` or `TOKEN`, depending on what authentication method was used. If you want to exclude all internal connections from the list, call this method with following arguments: [ [ ["internal", "=", True] ] ] `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/auth/sessions
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Returns true if two factor authorization is required for authorizing user's login.
/auth/two_factor_auth
/auth/twofactor
Returns the provisioning URI for the OTP. This can then be encoded in a QR Code and used to provision an OTP app like Google Authenticator.
/auth/twofactor/provisioning_uri
`otp_digits` represents number of allowed digits in the OTP. `window` extends the validity to `window` many counter ticks before and after the current one. `interval` is time duration in seconds specifying OTP expiration time from it's creation time.
/auth/twofactor
| Name | Description |
|---|---|
| body |
Generates a new secret for Two Factor Authentication. Returns boolean true on success.
/auth/twofactor/renew_secret
Returns boolean true if provided `token` is successfully authenticated.
/auth/twofactor/verify
| Name | Description |
|---|---|
| body |
Attach a disk to the boot pool, turning a stripe into a mirror. `expand` option will determine whether the new disk partition will be the maximum available or the same size as the current disk.
/boot/attach
| Name | Description |
|---|---|
| body |
Detach given `dev` from boot pool.
/boot/detach
| Name | Description |
|---|---|
| body |
Returns disks of the boot pool.
/boot/get_disks
Get Automatic Scrub Interval value in days.
/boot/get_scrub_interval
Returns the current state of the boot pool, including all vdevs, properties and datasets.
/boot/get_state
Replace device `label` on boot pool with `dev`.
/boot/replace
| Name | Description |
|---|---|
| body |
Scrub on boot pool.
/boot/scrub
Set Automatic Scrub Interval value in days.
/boot/set_scrub_interval
| Name | Description |
|---|---|
| body |
Query all Boot Environments with `query-filters` and `query-options`. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/bootenv
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Activates boot environment `id`.
/bootenv/id/{id}/activate
| Name | Description |
|---|---|
| id* |
String
Required
|
Delete `id` boot environment. This removes the clone from the system.
/bootenv/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Query all Boot Environments with `query-filters` and `query-options`. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/bootenv/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Update `id` boot environment name with a new provided valid `name`.
/bootenv/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Sets attributes boot environment `id`. Currently only `keep` attribute is allowed.
/bootenv/id/{id}/set_attribute
| Name | Description |
|---|---|
| id* |
String
Required
|
Create a new boot environment using `name`. If a new boot environment is desired which is a clone of another boot environment, `source` can be passed. Then, a new boot environment of `name` is created using boot environment `source` by cloning it. Ensure that `name` and `source` are valid boot environment names.
/bootenv
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/catalog
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Retrieve information of `item_name` `item_version_details.catalog` catalog item.
/catalog/get_item_details
| Name | Description |
|---|---|
| body |
/catalog/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/catalog/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
/catalog/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Retrieve item details for `label` catalog. `options.cache` is a boolean which when set will try to get items details for `label` catalog from cache if available. `options.cache_only` is a boolean which when set will force usage of cache only for retrieving catalog information. If the content for the catalog in question is not cached, no content would be returned. If `options.cache` is unset, this attribute has no effect. `options.retrieve_all_trains` is a boolean value which when set will retrieve information for all the trains present in the catalog ( it is set by default ). `options.trains` is a list of train name(s) which will allow selective filtering to retrieve only information of desired trains in a catalog. If `options.retrieve_all_trains` is set, it has precedence over `options.train`. `options.retrieve_versions` can be unset to skip retrieving version details of each catalog item. This can help in cases to optimize performance. Retrieving versions would be deprecated in the next major release from this endpoint.
/catalog/items
| Name | Description |
|---|---|
| body |
`catalog_create.preferred_trains` specifies trains which will be displayed in the UI directly for a user.
/catalog
| Name | Description |
|---|---|
| body |
Refresh all available catalogs from upstream.
/catalog/sync_all
Sync `label` catalog to retrieve latest changes from upstream.
/catalog/sync
| Name | Description |
|---|---|
| body |
Validates `label` catalog format which includes validating trains and applications with their versions. This does not test if an app version is valid in terms of kubernetes resources but instead ensures it has the correct format and files necessary for TrueNAS to use it.
/catalog/validate
| Name | Description |
|---|---|
| body |
Dictionary of popular ACME Servers with their directory URI endpoints which we display automatically in UI
/certificate/acme_server_choices
Returns a dictionary of predefined options for specific use cases i.e openvpn client/server configurations which can be used for creating certificate signing requests.
/certificate/certificate_signing_requests_profiles
Returns country choices for creating a certificate/csr.
/certificate/country_choices
Dictionary of supported EC curves.
/certificate/ec_curve_choices
Dictionary of choices for `ExtendedKeyUsage` extension which can be passed over to `usages` attribute.
/certificate/extended_key_usage_choices
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/certificate
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete certificate of `id`. If the certificate is an ACME based certificate, certificate service will try to revoke the certificate by updating it's status with the ACME server, if it fails an exception is raised and the certificate is not deleted from the system. However, if `force` is set to True, certificate is deleted from the system even if some error occurred while revoking the certificate with the ACME Server
/certificate/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/certificate/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update certificate of `id` Only name and revoked attribute can be updated. When `revoked` is enabled, the specified cert `id` is revoked and if it belongs to a CA chain which exists on this system, its serial number is added to the CA's certificate revocation list.
/certificate/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Dictionary of supported key types for certificates.
/certificate/key_type_choices
Create a new Certificate Certificates are classified under following types and the necessary keywords to be passed for `create_type` attribute to create the respective type of certificate 1) Internal Certificate - CERTIFICATE_CREATE_INTERNAL 2) Imported Certificate - CERTIFICATE_CREATE_IMPORTED 3) Certificate Signing Request - CERTIFICATE_CREATE_CSR 4) Imported Certificate Signing Request - CERTIFICATE_CREATE_IMPORTED_CSR 5) ACME Certificate - CERTIFICATE_CREATE_ACME By default, created certs use RSA keys. If an Elliptic Curve Key is desired, it can be specified with the `key_type` attribute. If the `ec_curve` attribute is not specified for the Elliptic Curve Key, then default to using "BrainpoolP384R1" curve. A type is selected by the Certificate Service based on `create_type`. The rest of the values in `data` are validated accordingly and finally a certificate is made based on the selected type. `cert_extensions` can be specified to set X509v3 extensions.
/certificate
| Name | Description |
|---|---|
| body |
Returns a dictionary of predefined options for specific use cases i.e openvpn client/server configurations which can be used for creating certificates.
/certificate/profiles
Returns certificate authorities which can be used by applications.
/chart/release/certificate_authority_choices
Returns certificates which can be used by applications.
/chart/release/certificate_choices
Returns kubernetes events for `release_name` Chart Release.
/chart/release/events
| Name | Description |
|---|---|
| body |
Query available chart releases. `query-options.extra.retrieve_resources` is a boolean when set will retrieve existing kubernetes resources in the chart namespace. `query-options.extra.history` is a boolean when set will retrieve all chart version upgrades for a chart release. `query-options.extra.include_chart_schema` is a boolean when set will retrieve the schema being used by the chart release in question. `query-options.extra.resource_events` is a boolean when set will retrieve individual events of each resource. This only has effect if `query-options.extra.retrieve_resources` is set. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/chart/release
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete existing chart release. This will delete the chart release from the kubernetes cluster and also remove any associated volumes / data. To clarify, host path volumes will not be deleted which live outside the chart release dataset.
/chart/release/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Query available chart releases. `query-options.extra.retrieve_resources` is a boolean when set will retrieve existing kubernetes resources in the chart namespace. `query-options.extra.history` is a boolean when set will retrieve all chart version upgrades for a chart release. `query-options.extra.include_chart_schema` is a boolean when set will retrieve the schema being used by the chart release in question. `query-options.extra.resource_events` is a boolean when set will retrieve individual events of each resource. This only has effect if `query-options.extra.retrieve_resources` is set. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/chart/release/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Update an existing chart release. `values` is configuration specified for the catalog item version in question which will be used to create the chart release.
/chart/release/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Available choices for NIC which can be added to a pod in a chart release.
/chart/release/nic_choices
Returns choices for console access to a chart release. Output is a dictionary with names of pods as keys and containing names of containers which the pod comprises of.
/chart/release/pod_console_choices
| Name | Description |
|---|---|
| body |
Returns choices for accessing logs of any container in any pod in a chart release.
/chart/release/pod_logs_choices
| Name | Description |
|---|---|
| body |
Retrieve available/desired pods status for a chart release and it's current state.
/chart/release/pod_status
| Name | Description |
|---|---|
| body |
Create a chart release for a catalog item. `release_name` is the name which will be used to identify the created chart release. `catalog` is a valid catalog id where system will look for catalog `item` details. `train` is which train to look for under `catalog` i.e stable / testing etc. `version` specifies the catalog `item` version. `values` is configuration specified for the catalog item version in question which will be used to create the chart release.
/chart/release
| Name | Description |
|---|---|
| body |
Update container images being used by `release_name` chart release. `redeploy` when set will redeploy pods which will result in chart release using newer updated versions of the container images.
/chart/release/pull_container_images
| Name | Description |
|---|---|
| body |
Redeploy will initiate a new rollout of the Helm chart according to upgrade strategy defined by the chart release workloads. A good example for redeploying is updating kubernetes pods with an updated container image.
/chart/release/redeploy
| Name | Description |
|---|---|
| body |
Remove `volume_name` ix_volume from `release_name` chart release.
/chart/release/remove_ix_volume
| Name | Description |
|---|---|
| body |
Rollback a chart release to a previous chart version. `item_version` is version which we want to rollback a chart release to. `rollback_snapshot` is a boolean value which when set will rollback snapshots of any PVC's or ix volumes being consumed by the chart release. `force_rollback` is a boolean which when set will force rollback operation to move forward even if no snapshots are found. This is only useful when `rollback_snapshot` is set. `recreate_resources` is a boolean which will delete and then create the kubernetes resources on rollback of chart release. This should be used with caution as if chart release is consuming immutable objects like a PVC, the rollback operation can't be performed and will fail as helm tries to do a 3 way patch for rollback. Rollback is functional for the actual configuration of the release at the `item_version` specified and any associated `ix_volumes` with any PVC's which were consuming chart release storage class.
/chart/release/rollback
| Name | Description |
|---|---|
| body |
Scale a `release_name` chart release to `scale_options.replica_count` specified. This will scale deployments/statefulset to replica count specified.
/chart/release/scale
| Name | Description |
|---|---|
| body |
Scale workloads in a chart release to specified `replica_count`.
/chart/release/scale_workloads
| Name | Description |
|---|---|
| body |
Returns choices for types of workloads which can be scaled up/down.
/chart/release/scaleable_resources
Upgrade `release_name` chart release. `upgrade_options.item_version` specifies to which item version chart release should be upgraded to. System will update container images being used by `release_name` chart release as a chart release upgrade is not considered complete until the images in use have also been updated to latest versions. During upgrade, `upgrade_options.values` can be specified to apply configuration changes for configuration changes for the chart release in question. When chart version is upgraded, system will automatically take a snapshot of `ix_volumes` in question which can be used to rollback later on.
/chart/release/upgrade
| Name | Description |
|---|---|
| body |
Retrieve upgrade summary for `release_name` which will include which container images will be updated and changelog for `options.item_version` chart version specified if applicable. If only container images need to be updated, changelog will be `null`. If chart release `release_name` does not require an upgrade, an error will be raised.
/chart/release/upgrade_summary
| Name | Description |
|---|---|
| body |
Returns ports in use by applications.
/chart/release/used_ports
Query all Cloud Sync Tasks with `query-filters` and `query-options`. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/cloudsync
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Aborts cloud sync task.
/cloudsync/id/{id}/abort
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Deletes cloud_sync entry `id`.
/cloudsync/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Query all Cloud Sync Tasks with `query-filters` and `query-options`. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/cloudsync/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Updates the cloud_sync entry `id` with `data`.
/cloudsync/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create the opposite of cloud sync task `id` (PULL if it was PUSH and vice versa).
/cloudsync/id/{id}/restore
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Run the cloud_sync job `id`, syncing the local data to remote.
/cloudsync/id/{id}/sync
| Name | Description |
|---|---|
| id* |
Integer
Required
|
/cloudsync/list_buckets
| Name | Description |
|---|---|
| body |
List contents of a remote bucket / directory. If remote supports buckets, path is constructed by two keys "bucket"/"folder" in `attributes`. If remote does not support buckets, path is constructed using "folder" key only in `attributes`. "folder" is directory name and "bucket" is bucket name for remote. Path examples: S3 Service `bucketname/directory/name` Dropbox Service `directory/name` `credentials` is a valid id of a Cloud Sync Credential which will be used to connect to the provider.
/cloudsync/list_directory
| Name | Description |
|---|---|
| body |
Lists all available drives and their types for given Microsoft OneDrive credentials.
/cloudsync/onedrive_list_drives
| Name | Description |
|---|---|
| body |
Creates a new cloud_sync entry.
/cloudsync
| Name | Description |
|---|---|
| body |
Returns a list of dictionaries of supported providers for Cloud Sync Tasks. `credentials_schema` is JSON schema for credentials attributes. `task_schema` is JSON schema for task attributes. `buckets` is a boolean value which is set to "true" if provider supports buckets. Example of a single provider: [ { "name": "AMAZON_CLOUD_DRIVE", "title": "Amazon Cloud Drive", "credentials_schema": [ { "property": "client_id", "schema": { "title": "Amazon Application Client ID", "_required_": true, "type": "string" } }, { "property": "client_secret", "schema": { "title": "Application Key", "_required_": true, "type": "string" } } ], "credentials_oauth": null, "buckets": false, "bucket_title": "Bucket", "task_schema": [] } ]
/cloudsync/providers
Run cloud sync task without creating it.
/cloudsync/sync_onetime
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/cloudsync/credentials
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete Cloud Sync Credentials of `id`.
/cloudsync/credentials/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/cloudsync/credentials/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update Cloud Sync Credentials of `id`.
/cloudsync/credentials/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create Cloud Sync Credentials. `attributes` is a dictionary of valid values which will be used to authorize with the `provider`.
/cloudsync/credentials
| Name | Description |
|---|---|
| body |
Verify if `attributes` provided for `provider` are authorized by the `provider`.
/cloudsync/credentials/verify
| Name | Description |
|---|---|
| body |
Reset database to configuration defaults. If `reboot` is true this job will reboot the system after its completed with a delay of 10 seconds.
/config/reset
| Name | Description |
|---|---|
| body |
/container
When `enable_image_updates` is set, system will check if existing container images need to be updated. System will basically check if we have an updated image hash available for the same tag available and if we do, user is alerted to update the image. A use case for unsetting this variable can be rate limits for docker registries, as each time we check if a single image needs update, we consume the rate limit and eventually it can hinder operations if the number of images to be checked is a lot.
/container
| Name | Description |
|---|---|
| body |
Retrieve container images present in the system. `query-options.extra.parse_tags` is a boolean which when set will have normalized tags to be retrieved for container images. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/container/image
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
`options.force` should be used to force delete an image even if it's in use by a stopped container.
/container/image/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Retrieve container images present in the system. `query-options.extra.parse_tags` is a boolean which when set will have normalized tags to be retrieved for container images. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/container/image/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
`from_image` is the name of the image to pull. Format for the name is "registry/repo/image" where registry may be omitted and it will default to docker registry in this case. `tag` specifies tag of the image and defaults to `null`. In case of `null` it will retrieve all the tags of the image. `docker_authentication` should be specified if image to be retrieved is under a private repository.
/container/image/pull
| Name | Description |
|---|---|
| body |
Will loop on a list of items for the given method, returning a list of dicts containing a result and error key. `description` contains format string for job progress (e.g. "Deleting snapshot {0[dataset]}@{0[name]}") Result will be the message returned by the method being called, or a string of an error, in which case the error key will be the exception
/core/bulk
| Name | Description |
|---|---|
| body |
/core/debug_mode_enabled
Setup middlewared for remote debugging. engines: - PTVS: Python Visual Studio - PYDEV: Python Dev (Eclipse/PyCharm) - REMOTE_PDB: Remote vanilla PDB (over TCP sockets) options: - secret: password for PTVS - host: required for PYDEV, hostname of local computer (developer workstation) - local_path: required for PYDEV, path for middlewared source in local computer (e.g. /home/user/freenas/src/middlewared/middlewared - threaded: run debugger in a new thread instead of event loop
/core/debug
| Name | Description |
|---|---|
| body |
Core helper to call a job marked for download. Non-`buffered` downloads will allow job to write to pipe as soon as download URL is requested, job will stay blocked meanwhile. `buffered` downloads must wait for job to complete before requesting download URL, job's pipe output will be buffered to ramfs. Returns the job id and the URL for download.
/core/download
| Name | Description |
|---|---|
| body |
Returns metadata for every possible event emitted from websocket server.
/core/get_events
Get the long running jobs. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/core/get_jobs
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Return methods metadata of every available service. `service` parameter is optional and filters the result for a single service.
/core/get_methods
| Name | Description |
|---|---|
| body |
Returns a list of all registered services.
/core/get_services
| Name | Description |
|---|---|
| body |
Retrieve last 1000 incoming/outgoing message(s) logged over websocket.
/core/get_websocket_messages
/core/job_abort
| Name | Description |
|---|---|
| body |
/core/job_update
| Name | Description |
|---|---|
| body |
/core/job_wait
| Name | Description |
|---|---|
| body |
Utility method which just returns "pong". Can be used to keep connection/authtoken alive instead of using "ping" protocol message.
/core/ping
Method that will send an ICMP echo request to "hostname" and will wait up to "timeout" for a reply.
/core/ping_remote
| Name | Description |
|---|---|
| body |
Resize terminal session (/websocket/shell) to cols x rows
/core/resize_shell
| Name | Description |
|---|---|
| body |
Get currently open websocket sessions. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/core/sessions
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Set `debug_mode` for middleware.
/core/set_debug_mode
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/cronjob
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete cronjob of `id`.
/cronjob/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/cronjob/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update cronjob of `id`.
/cronjob/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create a new cron job. `stderr` and `stdout` are boolean values which if `true`, represent that we would like to suppress standard error / standard output respectively.
/cronjob
| Name | Description |
|---|---|
| body |
Job to run cronjob task of `id`.
/cronjob/run
| Name | Description |
|---|---|
| body |
Returns a boolean if the ctdb cluster is healthy.
/ctdb/general/healthy
Return a list of public ip addresses in the ctdb cluster.
/ctdb/general/ips
| Name | Description |
|---|---|
| body |
Return a list of nodes in the ctdb cluster.
/ctdb/general/listnodes
Return node number for this node. This value should be static for life of cluster.
/ctdb/general/pnn
List the status of nodes in the ctdb cluster. `all_nodes`: Boolean if True, return status for all nodes in the cluster else return status of this node.
/ctdb/general/status
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/ctdb/private/ips
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/ctdb/private/ips/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update Private IP address from the ctdb cluster with pnn value of `id`. `id` integer representing the PNN value for the node. `enable` boolean. When True, enable the node else disable the node.
/ctdb/private/ips/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Add a ctdb private address to the cluster `ip` string representing an IP v4/v6 address
/ctdb/private/ips
| Name | Description |
|---|---|
| body |
Retrieve information about configured public IP addresses for the ctdb cluster. This call raise a CallError with errno set to ENXIO if this node is not in a state where it can provide accurate information about cluster. Examples problematic states are: - ctdb or glusterd are not running on this node - ctdb shared volume is not mounted `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/ctdb/public/ips
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Retrieve information about configured public IP addresses for the ctdb cluster. This call raise a CallError with errno set to ENXIO if this node is not in a state where it can provide accurate information about cluster. Examples problematic states are: - ctdb or glusterd are not running on this node - ctdb shared volume is not mounted `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/ctdb/public/ips/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update Public IP address in the ctdb cluster. `pnn` - cluster node number `ip` string representing the public ip address `enable` boolean. When True, enable the node else disable the node.
/ctdb/public/ips/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Add a ctdb public address to the cluster `pnn` node number of record to adjust `ip` string representing an IP v4/v6 address `netmask` integer representing a cidr notated netmask (i.e. 16/24/48/64 etc) `interface` string representing a network interface to apply the `ip`
/ctdb/public/ips
| Name | Description |
|---|---|
| body |
Get info for SERIAL/DISK/GPU device types.
/device/get_info
| Name | Description |
|---|---|
| body |
Retrieve choices for GPU PCI ids located in the system.
/device/gpu_pci_ids_choices
This method refreshes the directory services cache for users and groups that is used as a backing for `user.query` and `group.query` methods. The first cache fill in an Active Directory domain may take a significant amount of time to complete and so it is performed as within a job. The most likely situation in which a user may desire to refresh the directory services cache is after new users or groups to a remote directory server with the intention to have said users or groups appear in the results of the aforementioned account-related methods. A cache refresh is not required in order to use newly-added users and groups for in permissions and ACL related methods. Likewise, a cache refresh will not resolve issues with users being unable to authenticate to shares.
/directoryservices/cache_refresh
`DISABLED` Directory Service is disabled. `FAULTED` Directory Service is enabled, but not HEALTHY. Review logs and generated alert messages to debug the issue causing the service to be in a FAULTED state. `LEAVING` Directory Service is in process of stopping. `JOINING` Directory Service is in process of starting. `HEALTHY` Directory Service is enabled, and last status check has passed.
/directoryservices/get_state
Query disks. The following extra options are supported: include_expired: true - will also include expired disks (default: false) passwords: true - will not hide KMIP password for the disks (default: false) pools: true - will join pool name for each disk (default: false) `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/disk
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Helper method to get all disks that are not in use, either by the boot pool or the user pools.
/disk/get_unused
| Name | Description |
|---|---|
| body |
Query disks. The following extra options are supported: include_expired: true - will also include expired disks (default: false) passwords: true - will not hide KMIP password for the disks (default: false) pools: true - will join pool name for each disk (default: false) `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/disk/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Update disk of `id`. If extra options need to be passed to SMART which we don't already support, they can be passed by `smartoptions`. `critical`, `informational` and `difference` are integer values on which alerts for SMART are configured if the disk temperature crosses the assigned threshold for each respective attribute. If they are set to null, then SMARTD config values are used as defaults. Email of log level LOG_CRIT is issued when disk temperature crosses `critical`. Email of log level LOG_INFO is issued when disk temperature crosses `informational`. If temperature of a disk changes by `difference` degree Celsius since the last report, SMART reports this.
/disk/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Returns S.M.A.R.T. attributes values for specified disk name.
/disk/smart_attributes
| Name | Description |
|---|---|
| body |
Returns temperature for device `name` using specified S.M.A.R.T. `powermode`.
/disk/temperature
| Name | Description |
|---|---|
| body |
Returns temperatures for a list of devices (runs in parallel). See `disk.temperature` documentation for more details.
/disk/temperatures
| Name | Description |
|---|---|
| body |
Performs a wipe of a disk `dev`. It can be of the following modes: - QUICK: clean the first and last 32 megabytes on `dev` - FULL: write whole disk with zero's - FULL_RANDOM: write whole disk with random bytes
/disk/wipe
| Name | Description |
|---|---|
| body |
Query Name Servers with `query-filters` and `query-options`. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/dns/query
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
/dyndns
List supported Dynamic DNS Service Providers.
/dyndns/provider_choices
Update dynamic dns service configuration. `period` indicates how often the IP is checked in seconds. `ssl` if set to true, makes sure that HTTPS is used for the connection to the server which updates the DNS record.
/dyndns
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/enclosure
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/enclosure/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
/enclosure/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
/enclosure/set_slot_status
| Name | Description |
|---|---|
| body |
Restart the keepavlived service which will cause any VIP addresses on this controller to be migrated to the other controller. This will cause a failover event if run on the master controller. If this is run on the passive controller it will do 1 of 2 things: 1: if there are no VIP(s) on the passive controller, then this will do nothing. 2: if there are VIP(s) on the passive controller, then the VIP(s) will be migrated to the active controller. A failover event will be triggered but it will do nothing since the active will already have the zpool(s) imported.
/failover/become_passive
Call a method in the other node.
/failover/call_remote
| Name | Description |
|---|---|
| body |
/failover/control
| Name | Description |
|---|---|
| body |
Force this controller to become MASTER, if it's not already.
/failover/force_master
/failover
Returns the hardware type for an HA system. ECHOSTREAM ECHOWARP PUMA BHYVE MANUAL
/failover/hardware
Returns True if there is an ongoing failover event.
/failover/in_progress
Checks whether this instance is licensed as a HA unit.
/failover/licensed
Returns the slot position in the chassis that the controller is located. A - First node B - Seconde Node MANUAL - slot position in chassis could not be determined
/failover/node
Update failover state. `disabled` When true indicates that HA will be disabled. `master` Marks the particular node in the chassis as the master node. The standby node will have the opposite value. `timeout` is the time to WAIT until a failover occurs when a network event occurs on an interface that is marked critical for failover AND HA is enabled and working appropriately. The default time to wait is 2 seconds. **NOTE** This setting does NOT effect the `disabled` or `master` parameters.
/failover
| Name | Description |
|---|---|
| body |
Get the current HA status. Returns: MASTER BACKUP ELECTING IMPORTING ERROR SINGLE
/failover/status
Sync database and files from the other controller.
/failover/sync_from_peer
Sync database and files to the other controller. `reboot` as true will reboot the other controller after syncing.
/failover/sync_to_peer
| Name | Description |
|---|---|
| body |
Unlock datasets in HA, syncing passphrase between controllers and forcing this controller to be MASTER importing the pools.
/failover/unlock
| Name | Description |
|---|---|
| body |
Perform the last stage of an HA upgrade. This will activate the new boot environment on the Standby Controller and reboot it.
/failover/upgrade_finish
Verify if HA upgrade is pending. `upgrade_finish` needs to be called to finish the HA upgrade process if this method returns true.
/failover/upgrade_pending
Upgrades both controllers. Files will be downloaded to the Active Controller and then transferred to the Standby Controller. Upgrade process will start concurrently on both nodes. Once both upgrades are applied, the Standby Controller will reboot. This job will wait for that job to complete before finalizing. A file can be uploaded to this end point. This end point is special, please refer to Jobs section in Websocket API documentation for details.
/failover/upgrade
| Name | Description |
|---|---|
| body |
Returns True if the ACL can be fully expressed as a file mode without losing any access rules. Paths on clustered volumes may be specifed with the path prefix `CLUSTER:<volume name>`. For example, to list directories in the directory 'data' in the clustered volume `smb01`, the path should be specified as `CLUSTER:smb01/data`.
/filesystem/acl_is_trivial
| Name | Description |
|---|---|
| body |
Check if `username` is able to access `path` with specific `permissions`. At least one of `read/write/execute` permission must be specified for checking with each of these defaulting to `null`. `null` for `read/write/execute` represents that the permission should not be checked.
/filesystem/can_access_as_user
| Name | Description |
|---|---|
| body |
Change owner or group of file at `path`. `uid` and `gid` specify new owner of the file. If either key is absent or None, then existing value on the file is not changed. `recursive` performs action recursively, but does not traverse filesystem mount points. If `traverse` and `recursive` are specified, then the chown operation will traverse filesystem mount points.
/filesystem/chown
| Name | Description |
|---|---|
| body |
`DEPRECATED` Returns list of names of ACL templates. Wrapper around filesystem.acltemplate.query.
/filesystem/default_acl_choices
| Name | Description |
|---|---|
| body |
`DEPRECATED` Returns a default ACL depending on the usage specified by `acl_type`. If an admin group is defined, then an entry granting it full control will be placed at the top of the ACL. Optionally may pass `share_type` to argument to get share-specific template ACL.
/filesystem/get_default_acl
| Name | Description |
|---|---|
| body |
Return ACL of a given path. This may return a POSIX1e ACL or a NFSv4 ACL. The acl type is indicated by the `acltype` key. `simplified` - effect of this depends on ACL type on underlying filesystem. In the case of NFSv4 ACLs simplified permissions and flags are returned for ACL entries where applicable. NFSv4 errata below. In the case of POSIX1E ACls, this setting has no impact on returned ACL. `resolve_ids` - adds additional `who` key to each ACL entry, that converts the numeric id to a user name or group name. In the case of owner@ and group@ (NFSv4) or USER_OBJ and GROUP_OBJ (POSIX1E), st_uid or st_gid will be converted from stat() return for file. In the case of MASK (POSIX1E), OTHER (POSIX1E), everyone@ (NFSv4), key `who` will be included, but set to null. In case of failure to resolve the id to a name, `who` will be set to null. This option should only be used if resolving ids to names is required. Errata about ACLType NFSv4: `simplified` returns a shortened form of the ACL permset and flags where applicable. If permissions have been simplified, then the `perms` object will contain only a single `BASIC` key with a string describing the underlying permissions set. `TRAVERSE` sufficient rights to traverse a directory, but not read contents. `READ` sufficient rights to traverse a directory, and read file contents. `MODIFIY` sufficient rights to traverse, read, write, and modify a file. `FULL_CONTROL` all permissions. If the permisssions do not fit within one of the pre-defined simplified permissions types, then the full ACL entry will be returned.
/filesystem/getacl
| Name | Description |
|---|---|
| body |
Retrieves boolean which is set when immutable flag is set on `path`.
/filesystem/is_immutable
| Name | Description |
|---|---|
| body |
Get the contents of a directory. Paths on clustered volumes may be specifed with the path prefix `CLUSTER:<volume name>`. For example, to list directories in the directory 'data' in the clustered volume `smb01`, the path should be specified as `CLUSTER:smb01/data`. Each entry of the list consists of: name(str): name of the file path(str): absolute path of the entry realpath(str): absolute real path of the entry (if SYMLINK) type(str): DIRECTORY | FILESYSTEM | SYMLINK | OTHER size(int): size of the entry mode(int): file mode/permission uid(int): user id of entry owner gid(int): group id of entry onwer acl(bool): extended ACL is present on file
/filesystem/listdir
| Name | Description |
|---|---|
| body |
Create a directory at the specified path.
/filesystem/mkdir
| Name | Description |
|---|---|
| body |
Set/Unset immutable flag at `path`. `set_flag` when set will set immutable flag and when unset will unset immutable flag at `path`.
/filesystem/set_immutable
| Name | Description |
|---|---|
| body |
Set ACL of a given path. Takes the following parameters: `path` full path to directory or file. Paths on clustered volumes may be specifed with the path prefix `CLUSTER:<volume name>`. For example, to list directories in the directory 'data' in the clustered volume `smb01`, the path should be specified as `CLUSTER:smb01/data`. `dacl` ACL entries. Formatting depends on the underlying `acltype`. NFS4ACL requires NFSv4 entries. POSIX1e requires POSIX1e entries. `uid` the desired UID of the file user. If set to None (the default), then user is not changed. `gid` the desired GID of the file group. If set to None (the default), then group is not changed. `recursive` apply the ACL recursively `traverse` traverse filestem boundaries (ZFS datasets) `strip` convert ACL to trivial. ACL is trivial if it can be expressed as a file mode without losing any access rules. `canonicalize` reorder ACL entries so that they are in concanical form as described in the Microsoft documentation MS-DTYP 2.4.5 (ACL). This only applies to NFSv4 ACLs. For case of NFSv4 ACLs USER_OBJ, GROUP_OBJ, and EVERYONE with owner@, group@, everyone@ for consistency with getfacl and setfacl. If one of aforementioned special tags is used, 'id' must be set to None. An inheriting empty everyone@ ACE is appended to non-trivial ACLs in order to enforce Windows expectations regarding permissions inheritance. This entry is removed from NT ACL returned to SMB clients when 'ixnas' samba VFS module is enabled.
/filesystem/setacl
| Name | Description |
|---|---|
| body |
Set unix permissions on given `path`. Paths on clustered volumes may be specifed with the path prefix `CLUSTER:<volume name>`. For example, to list directories in the directory 'data' in the clustered volume `smb01`, the path should be specified as `CLUSTER:smb01/data`. If `mode` is specified then the mode will be applied to the path and files and subdirectories depending on which `options` are selected. Mode should be formatted as string representation of octal permissions bits. `uid` the desired UID of the file user. If set to None (the default), then user is not changed. `gid` the desired GID of the file group. If set to None (the default), then group is not changed. `stripacl` setperm will fail if an extended ACL is present on `path`, unless `stripacl` is set to True. `recursive` remove ACLs recursively, but do not traverse dataset boundaries. `traverse` remove ACLs from child datasets. If no `mode` is set, and `stripacl` is True, then non-trivial ACLs will be converted to trivial ACLs. An ACL is trivial if it can be expressed as a file mode without losing any access rules.
/filesystem/setperm
| Name | Description |
|---|---|
| body |
Return the filesystem stat(2) for a given `path`. Paths on clustered volumes may be specifed with the path prefix `CLUSTER:<volume name>`. For example, to list directories in the directory 'data' in the clustered volume `smb01`, the path should be specified as `CLUSTER:smb01/data`.
/filesystem/stat
| Name | Description |
|---|---|
| body |
Return stats from the filesystem of a given path. Paths on clustered volumes may be specifed with the path prefix `CLUSTER:<volume name>`. For example, to list directories in the directory 'data' in the clustered volume `smb01`, the path should be specified as `CLUSTER:smb01/data`. Raises: CallError(ENOENT) - Path not found
/filesystem/statfs
| Name | Description |
|---|---|
| body |
Retrieve list of available ACL templates for a given `path`. Supports `query-filters` and `query-options`. `format-options` gives additional options to alter the results of the template query: `canonicalize` - place ACL entries for NFSv4 ACLs in Microsoft canonical order. `ensure_builtins` - ensure all results contain entries for `builtin_users` and `builtin_administrators` groups. `resolve_names` - convert ids in ACL entries into names.
/filesystem/acltemplate/by_path
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/filesystem/acltemplate
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
/filesystem/acltemplate/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/filesystem/acltemplate/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
update filesystem ACL template with `id`.
/filesystem/acltemplate/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create a new filesystem ACL template.
/filesystem/acltemplate
| Name | Description |
|---|---|
| body |
/ftp
Update ftp service configuration. `clients` is an integer value which sets the maximum number of simultaneous clients allowed. It defaults to 32. `ipconnections` is an integer value which shows the maximum number of connections per IP address. It defaults to 0 which equals to unlimited. `timeout` is the maximum number of seconds that proftpd will allow clients to stay connected without receiving any data on either the control or data connection. `timeout_notransfer` is the maximum number of seconds a client is allowed to spend connected, after authentication, without issuing a command which results in creating an active or passive data connection (i.e. sending/receiving a file, or receiving a directory listing). `rootlogin` is a boolean value which when configured to true enables login as root. This is generally discouraged because of the security risks. `onlyanonymous` allows anonymous FTP logins with access to the directory specified by `anonpath`. `banner` is a message displayed to local login users after they successfully authenticate. It is not displayed to anonymous login users. `filemask` sets the default permissions for newly created files which by default are 077. `dirmask` sets the default permissions for newly created directories which by default are 077. `resume` if set allows FTP clients to resume interrupted transfers. `fxp` if set to true indicates that File eXchange Protocol is enabled. Generally it is discouraged as it makes the server vulnerable to FTP bounce attacks. `defaultroot` when set ensures that for local users, home directory access is only granted if the user is a member of group wheel. `ident` is a boolean value which when set to true indicates that IDENT authentication is required. If identd is not running on the client, this can result in timeouts. `masqaddress` is the public IP address or hostname which is set if FTP clients cannot connect through a NAT device. `localuserbw` is a positive integer value which indicates maximum upload bandwidth in KB/s for local user. Default of zero indicates unlimited upload bandwidth ( from the FTP server configuration ). `localuserdlbw` is a positive integer value which indicates maximum download bandwidth in KB/s for local user. Default of zero indicates unlimited download bandwidth ( from the FTP server configuration ). `anonuserbw` is a positive integer value which indicates maximum upload bandwidth in KB/s for anonymous user. Default of zero indicates unlimited upload bandwidth ( from the FTP server configuration ). `anonuserdlbw` is a positive integer value which indicates maximum download bandwidth in KB/s for anonymous user. Default of zero indicates unlimited download bandwidth ( from the FTP server configuration ). `tls` is a boolean value which when set indicates that encrypted connections are enabled. This requires a certificate to be configured first with the certificate service and the id of certificate is passed on in `ssltls_certificate`. `tls_policy` defines whether the control channel, data channel, both channels, or neither channel of an FTP session must occur over SSL/TLS. `tls_opt_enable_diags` is a boolean value when set, logs verbosely. This is helpful when troubleshooting a connection. `options` is a string used to add proftpd(8) parameters not covered by ftp service.
/ftp
| Name | Description |
|---|---|
| body |
Add `url` webhook that will be called with a JSON formatted POST request that will include the event that was triggered along with the relevant data. `url` is a http address (i.e. http://192.168.1.50/endpoint) `bearer_token` is a bearer token `secret` secret to encode the JWT message NOTE: This webhook will be synchronized to all peers in the trusted storage pool.
/gluster/eventsd/create
| Name | Description |
|---|---|
| body |
Delete `url` webhook `url` is a http address (i.e. http://192.168.1.50/endpoint)
/gluster/eventsd/delete
| Name | Description |
|---|---|
| body |
Sync the webhooks config file to all peers in the trusted storage pool
/gluster/eventsd/sync
List the current webhooks (if any)
/gluster/eventsd/webhooks
Check if gluster volume is FUSE mounted locally. `name` String representing name of the gluster volume
/gluster/fuse/is_mounted
| Name | Description |
|---|---|
| body |
Mount a gluster volume using the gluster FUSE client. `name` String representing the name of the gluster volume `all` Boolean if True locally FUSE mount all detected gluster volumes `raise` Boolean if True raise a CallError if the FUSE mount fails
/gluster/fuse/mount
| Name | Description |
|---|---|
| body |
Unmount a locally FUSE mounted gluster volume. `name` String representing the name of the gluster volume `all` Boolean if True umount all locally detected FUSE mounted gluster volumes `raise` Boolean if True raise a CallError if the FUSE mount fails
/gluster/fuse/umount
| Name | Description |
|---|---|
| body |
Add a `secret` key used to encode/decode JWT messages for sending/receiving gluster events. `secret` String representing the key to be used to encode/decode JWT messages `force` Boolean if set to True, will forcefully wipe any existing jwt key for this peer. Note, if forcefully adding a new key, the other peers in the TSP will also need to be sent this key. Note: this secret is only used for messages that are destined for the api endpoint at http://*:6000/_clusterevents for each peer in the trusted storage pool.
/gluster/localevents/add_jwt_secret
| Name | Description |
|---|---|
| body |
Return the secret key used to encode/decode JWT messages for sending/receiving gluster events. Note: this secret is only used for messages that are destined for the api endpoint at http://*:6000/_clusterevents for each peer in the trusted storage pool.
/gluster/localevents/get_set_jwt_secret
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/gluster/peer
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Remove peer of `id` from the Trusted Storage Pool. `id` String representing the uuid of the peer
/gluster/peer/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/gluster/peer/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Return list of VIP(v4/v6) addresses available on the system
/gluster/peer/ips_available
Add peer to the Trusted Storage Pool. `hostname` String representing an IP(v4/v6) address or DNS name
/gluster/peer
| Name | Description |
|---|---|
| body |
List the status of peers in the Trusted Storage Pool. `localhost` Boolean if True, include localhost else exclude localhost
/gluster/peer/status
| Name | Description |
|---|---|
| body |
Start a fix-layout operation for a given gluster volume. `name` String representing the gluster volume.
/gluster/rebalance/fix_layout
| Name | Description |
|---|---|
| body |
Start a rebalance operation for a given gluster volume. `name` String representing the gluster volume. `force` Boolean, when True will forcefully start the rebalance operation.
/gluster/rebalance/start
| Name | Description |
|---|---|
| body |
Return the status of a rebalance operation for a given gluster volume. `name` String representing the gluster volume.
/gluster/rebalance/status
| Name | Description |
|---|---|
| body |
Stop a rebalance operation for a given gluster volume. `name` String representing the gluster volume.
/gluster/rebalance/stop
| Name | Description |
|---|---|
| body |
Add bricks to a gluster volume. `name` String representing name of gluster volume `bricks` List representing the brick paths `peer_name` String representing IP or DNS name of the peer `peer_path` String representing the full path of the brick `replica` Integer replicating replica count `arbiter` Integer replicating arbiter count `force` Boolean, if True, forcefully add brick(s)
/gluster/volume/addbrick
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/gluster/volume
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete a gluster volume. `id` String representing name of gluster volume to be deleted
/gluster/volume/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/gluster/volume/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Return information about gluster volume(s). `name` String representing name of gluster volume
/gluster/volume/info
| Name | Description |
|---|---|
| body |
Return list of gluster volumes.
/gluster/volume/list
Reset volumes options. If `opt` is not provided, then all options will be reset. `name` String representing name of gluster volume `opt` String representing name of the option to reset `force` Boolean, if True forcefully reset option(s)
/gluster/volume/optreset
| Name | Description |
|---|---|
| body |
Set gluster volume options. `name` String representing name of gluster volume `opts` Dict where --key-- is the name of the option --value-- is the value to be given to the option
/gluster/volume/optset
| Name | Description |
|---|---|
| body |
Create a gluster volume. `name` String representing name to be given to the volume `bricks` List representing the brick paths `peer_name` String representing IP or DNS name of the peer `peer_path` String representing the full path of the brick `replica` Integer representing number of replica bricks `arbiter` Integer representing number of arbiter bricks `disperse` Integer representing number of disperse bricks `disperse_data` Integer representing number of disperse data bricks `redundancy` Integer representing number of redundancy bricks `force` Boolean, if True ignore potential warnings
/gluster/volume
| Name | Description |
|---|---|
| body |
Enable/Disable the quota for a given gluster volume. `name` String representing name of gluster volume `enable` Boolean, if True enable quota else disable it
/gluster/volume/quota
| Name | Description |
|---|---|
| body |
Perform a remove operation on the brick(s) in the gluster volume. `name` String representing name of gluster volume `bricks` List representing the brick paths `peer_name` String representing IP or DNS name of the peer `peer_path` String representing the full path of the brick `operation` String representing the operation to be performed `START` Start the removal of the brick(s) `STOP` Stop the removal of the brick(s) `COMMIT` Commit the removal of the brick(s) `STATUS` Display status of the removal of the brick(s) `FORCE` Force the removal of the brick(s) `replica` Integer representing replica count
/gluster/volume/removebrick
| Name | Description |
|---|---|
| body |
Commit the replacement of a brick. `name` String representing name of gluster volume `src_brick` Dict where `peer_name` key is a string representing IP or DNS name of the peer `peer_path` key is a string representing the full path of the brick `new_brick` Dict where `peer_name` key is a string representing IP or DNS name of the peer `peer_path` key is a string representing the full path of the brick
/gluster/volume/replacebrick
| Name | Description |
|---|---|
| body |
Restart a gluster volume. `name` String representing name of gluster volume `force` Boolean, if True forcefully restart the gluster volume
/gluster/volume/restart
| Name | Description |
|---|---|
| body |
Start a gluster volume. `name` String representing name of gluster volume `force` Boolean, if True forcefully start the gluster volume
/gluster/volume/start
| Name | Description |
|---|---|
| body |
Return detailed information about gluster volume. `name` String representing name of gluster volume `verbose` Boolean, If False, only return brick information
/gluster/volume/status
| Name | Description |
|---|---|
| body |
Stop a gluster volume. `name` String representing name of gluster volume `force` Boolean, if True forcefully stop the gluster volume
/gluster/volume/stop
| Name | Description |
|---|---|
| body |
Query groups with `query-filters` and `query-options`. As a performance optimization, only local groups will be queried by default. Expanded information may be requested by specifying the extra option `"extra": {"additional_information": []}`. The following `additional_information` options are supported: `SMB` - include Windows SID and NT Name for group. If this option is not specified, then these keys will have `null` value. `DS` - include groups from Directory Service (LDAP or Active Directory) in results `"extra": {"search_dscache": true}` is a legacy method of querying for directory services groups. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/group
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Returns dictionary containing information from struct grp for the group specified by either the groupname or gid. Bypasses group cache.
/group/get_group_obj
| Name | Description |
|---|---|
| body |
Get the next available/free gid.
/group/get_next_gid
Delete group `id`. The `delete_users` option deletes all users that have this group as their primary group.
/group/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Query groups with `query-filters` and `query-options`. As a performance optimization, only local groups will be queried by default. Expanded information may be requested by specifying the extra option `"extra": {"additional_information": []}`. The following `additional_information` options are supported: `SMB` - include Windows SID and NT Name for group. If this option is not specified, then these keys will have `null` value. `DS` - include groups from Directory Service (LDAP or Active Directory) in results `"extra": {"search_dscache": true}` is a legacy method of querying for directory services groups. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/group/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update attributes of an existing group.
/group/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create a new group. If `gid` is not provided it is automatically filled with the next one available. `allow_duplicate_gid` allows distinct group names to share the same gid. `users` is a list of user ids (`id` attribute from `user.query`). `smb` specifies whether the group should be mapped into an NT group.
/group
| Name | Description |
|---|---|
| body |
Returns array of valid idmap backend choices per directory service.
/idmap/backend_choices
This returns full information about idmap backend options. Not all `options` are valid for every backend.
/idmap/backend_options
Stop samba, remove the winbindd_cache.tdb file, start samba, flush samba's cache. This should be performed after finalizing idmap changes.
/idmap/clear_idmap_cache
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/idmap
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete a domain by id. Deletion of default system domains is not permitted. In case of registry config for clustered server, this will remove all smb4.conf entries for the domain associated with the id.
/idmap/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/idmap/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update a domain by id.
/idmap/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Returns a list of supported keys for the specified idmap backend.
/idmap/options_choices
| Name | Description |
|---|---|
| body |
Create a new IDMAP domain. These domains must be unique. This table will be automatically populated after joining an Active Directory domain if "allow trusted domains" is set to True in the AD service configuration. There are three default system domains: DS_TYPE_ACTIVEDIRECTORY, DS_TYPE_LDAP, DS_TYPE_DEFAULT_DOMAIN. The system domains correspond with the idmap settings under Active Directory, LDAP, and SMB respectively. `name` the pre-windows 2000 domain name. `DNS_domain_name` DNS name of the domain. `idmap_backend` provides a plugin interface for Winbind to use varying backends to store SID/uid/gid mapping tables. The correct setting depends on the environment in which the NAS is deployed. `range_low` and `range_high` specify the UID and GID range for which this backend is authoritative. `certificate_id` references the certificate ID of the SSL certificate to use for certificate-based authentication to a remote LDAP server. This parameter is not supported for all idmap backends as some backends will generate SID to ID mappings algorithmically without causing network traffic. `options` are additional parameters that are backend-dependent: `AD` idmap backend options: `unix_primary_group` If True, the primary group membership is fetched from the LDAP attributes (gidNumber). If False, the primary group membership is calculated via the "primaryGroupID" LDAP attribute. `unix_nss_info` if True winbind will retrieve the login shell and home directory from the LDAP attributes. If False or if the AD LDAP entry lacks the SFU attributes the smb4.conf parameters `template shell` and `template homedir` are used. `schema_mode` Defines the schema that idmap_ad should use when querying Active Directory regarding user and group information. This can be either the RFC2307 schema support included in Windows 2003 R2 or the Service for Unix (SFU) schema. For SFU 3.0 or 3.5 please choose "SFU", for SFU 2.0 please choose "SFU20". The behavior of primary group membership is controlled by the unix_primary_group option. `AUTORID` idmap backend options: `readonly` sets the module to read-only mode. No new ranges will be allocated and new mappings will not be created in the idmap pool. `ignore_builtin` ignores mapping requests for the BUILTIN domain. `LDAP` idmap backend options: `ldap_base_dn` defines the directory base suffix to use for SID/uid/gid mapping entries. `ldap_user_dn` defines the user DN to be used for authentication. `ldap_url` specifies the LDAP server to use for SID/uid/gid map entries. `ssl` specifies whether to encrypt the LDAP transport for the idmap backend. `NSS` idmap backend options: `linked_service` specifies the auxiliary directory service ID provider. `RFC2307` idmap backend options: `domain` specifies the domain for which the idmap backend is being created. Numeric id, short-form domain name, or long-form DNS domain name of the domain may be specified. Entry must be entered as it appears in `idmap.domain`. `range_low` and `range_high` specify the UID and GID range for which this backend is authoritative. `ldap_server` defines the type of LDAP server to use. This can either be an LDAP server provided by the Active Directory Domain (ad) or a stand-alone LDAP server. `bind_path_user` specfies the search base where user objects can be found in the LDAP server. `bind_path_group` specifies the search base where group objects can be found in the LDAP server. `user_cn` query cn attribute instead of uid attribute for the user name in LDAP. `realm` append @realm to cn for groups (and users if user_cn is set) in LDAP queries. `ldmap_domain` when using the LDAP server in the Active Directory server, this allows one to specify the domain where to access the Active Directory server. This allows using trust relationships while keeping all RFC 2307 records in one place. This parameter is optional, the default is to access the AD server in the current domain to query LDAP records. `ldap_url` when using a stand-alone LDAP server, this parameter specifies the LDAP URL for accessing the LDAP server. `ldap_user_dn` defines the user DN to be used for authentication. `ldap_user_dn_password` is the password to be used for LDAP authentication. `realm` defines the realm to use in the user and group names. This is only required when using cn_realm together with a stand-alone ldap server. `RID` backend options: `sssd_compat` generate idmap low range based on same algorithm that SSSD uses by default.
/idmap
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/initshutdownscript
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete init/shutdown task of `id`.
/initshutdownscript/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/initshutdownscript/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update initshutdown script task of `id`.
/initshutdownscript/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create an initshutdown script task. `type` indicates if a command or script should be executed at `when`. There are three choices for `when`: 1) PREINIT - This is early in the boot process before all the services / rc scripts have started 2) POSTINIT - This is late in the boot process when most of the services / rc scripts have started 3) SHUTDOWN - This is on shutdown `timeout` is an integer value which indicates time in seconds which the system should wait for the execution of script/command. It should be noted that a hard limit for a timeout is configured by the base OS, so when a script/command is set to execute on SHUTDOWN, the hard limit configured by the base OS is changed adding the timeout specified by script/command so it can be ensured that it executes as desired and is not interrupted by the base OS's limit.
/initshutdownscript
| Name | Description |
|---|---|
| body |
Return available interface choices that can be added to a `br` (bridge) interface. `id` is name of existing bridge interface on the system that will have its member interfaces included.
/interface/bridge_members_choices
| Name | Description |
|---|---|
| body |
After interfaces changes are committed with checkin timeout this method needs to be called within that timeout limit to prevent reverting the changes. This is to ensure user verifies the changes went as planned and its working.
/interface/checkin
Returns whether or not we are waiting user to checkin the applied network changes before they are rolled back. Value is in number of seconds or null.
/interface/checkin_waiting
Choices of available network interfaces. `bridge_members` will include BRIDGE members. `lag_ports` will include LINK_AGGREGATION ports. `vlan_parent` will include VLAN parent interface. `exclude` is a list of interfaces prefix to remove. `include` is a list of interfaces that should not be removed.
/interface/choices
| Name | Description |
|---|---|
| body |
Commit/apply pending interfaces changes. `rollback` as true (default) will rollback changes in case they fail to apply. `checkin_timeout` is the time in seconds it will wait for the checkin call to acknowledge the interfaces changes happened as planned from the user. If checkin does not happen within this period of time the changes will get reverted.
/interface/commit
| Name | Description |
|---|---|
| body |
Query Interfaces with `query-filters` and `query-options` `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/interface
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Returns whether there are pending interfaces changes to be applied or not.
/interface/has_pending_changes
Delete Interface of `id`.
/interface/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Query Interfaces with `query-filters` and `query-options` `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/interface/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Update Interface of `id`.
/interface/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Get all IPv4 / Ipv6 from all valid interfaces, excluding tap and epair. `loopback` will return loopback interface addresses. `any` will return wildcard addresses (0.0.0.0 and ::). `static` when enabled will ensure we only return static ip's configured. Returns a list of dicts - eg - [ { "type": "INET6", "address": "fe80::5054:ff:fe16:4aac", "netmask": 64 }, { "type": "INET", "address": "192.168.122.148", "netmask": 24, "broadcast": "192.168.122.255" }, ]
/interface/ip_in_use
| Name | Description |
|---|---|
| body |
Available lacpdu rate policies for the LACP lagg type interfaces.
/interface/lacpdu_rate_choices
Return available interface choices that can be added to a `bond` (lag) interface. `id` is name of existing bond interface on the system that will have its member interfaces included.
/interface/lag_ports_choices
| Name | Description |
|---|---|
| body |
Create virtual interfaces (Link Aggregation, VLAN) For BRIDGE `type` the following attribute is required: bridge_members. For LINK_AGGREGATION `type` the following attributes are required: lag_ports, lag_protocol. For VLAN `type` the following attributes are required: vlan_parent_interface, vlan_tag and vlan_pcp.
/interface
| Name | Description |
|---|---|
| body |
Rollback pending interfaces changes.
/interface/rollback
Returns which services will be set to listen on 0.0.0.0 (and, thus, restarted) on sync. Example result: [ // Samba service will be set ot listen on 0.0.0.0 and restarted because it was set up to listen on // 192.168.0.1 which is being removed. {"type": "SYSTEM_SERVICE", "service": "cifs", "ips": ["192.168.0.1"]}, ]
/interface/services_restarted_on_sync
Return available interface choices for `vlan_parent_interface` attribute.
/interface/vlan_parent_interface_choices
Available transmit hash policies for the LACP or LOADBALANCE lagg type interfaces.
/interface/xmit_hash_policy_choices
Return enabled, disabled and supported capabilities (also known as features) on a given interface. `name` String representing name of the interface
/interface/capabilities/get
| Name | Description |
|---|---|
| body |
Enable or Disable capabilties (also known as features) on a given interface. `name` String representing name of the interface `capabilities` List representing capabilities to be acted upon `action` String when set to 'ENABLE' will enable `capabilities` else if set to `DISABLE` will disable `capabilities`.
/interface/capabilities/set
| Name | Description |
|---|---|
| body |
Return a list with the IPMI channels available.
/ipmi/channels
Clear IPMI System Event Log
/ipmi/clear_sel
Query all IPMI Channels with `query-filters` and `query-options`. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/ipmi
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Query all IPMI Channels with `query-filters` and `query-options`. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/ipmi/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update `id` IPMI Configuration. `ipaddress` is a valid ip which will be used to connect to the IPMI interface. `netmask` is the subnet mask associated with `ipaddress`. `dhcp` is a boolean value which if unset means that `ipaddress`, `netmask` and `gateway` must be set.
/ipmi/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Turn on IPMI chassis identify light. To turn off specify 0 as `seconds`.
/ipmi/identify
| Name | Description |
|---|---|
| body |
Returns a boolean true value indicating if ipmi device is loaded.
/ipmi/is_loaded
Query IPMI System Event Log `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/ipmi/query_sel
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/iscsi/auth
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete iSCSI Authorized Access of `id`.
/iscsi/auth/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/iscsi/auth/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update iSCSI Authorized Access of `id`.
/iscsi/auth/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create an iSCSI Authorized Access. `tag` should be unique among all configured iSCSI Authorized Accesses. `secret` and `peersecret` should have length between 12-16 letters inclusive. `peeruser` and `peersecret` are provided only when configuring mutual CHAP. `peersecret` should not be similar to `secret`.
/iscsi/auth
| Name | Description |
|---|---|
| body |
Return a dict of available zvols that can be used when creating an extent. `ignore` is a list of paths (i.e. ['zvol/cargo/zvol01',]) that will be ignored and included in the returned dict of available zvols even if they are already being used. For example, if zvol/cargo/zvol01 has already been added to an extent, and you pass that path in to this method then it will be returned (even though it's being used).
/iscsi/extent/disk_choices
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/iscsi/extent
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete iSCSI Extent of `id`. If `id` iSCSI Extent's `type` was configured to FILE, `remove` can be set to remove the configured file.
/iscsi/extent/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/iscsi/extent/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update iSCSI Extent of `id`.
/iscsi/extent/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create an iSCSI Extent. When `type` is set to FILE, attribute `filesize` is used and it represents number of bytes. `filesize` if not zero should be a multiple of `blocksize`. `path` is a required attribute with `type` set as FILE. With `type` being set to DISK, a valid ZVOL is required. `insecure_tpc` when enabled allows an initiator to bypass normal access control and access any scannable target. This allows xcopy operations otherwise blocked by access control. `xen` is a boolean value which is set to true if Xen is being used as the iSCSI initiator. `ro` when set to true prevents the initiator from writing to this LUN.
/iscsi/extent
| Name | Description |
|---|---|
| body |
Returns whether iSCSI ALUA is enabled or not.
/iscsi/global/alua_enabled
Return currently connected clients count.
/iscsi/global/client_count
/iscsi/global
`alua` is a no-op for FreeNAS.
/iscsi/global
| Name | Description |
|---|---|
| body |
Get a list of currently running iSCSI sessions. This includes initiator and target names and the unique connection IDs. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/iscsi/global/sessions
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/iscsi/host
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Returns initiator groups associated with host `id`.
/iscsi/host/get_initiators
| Name | Description |
|---|---|
| body |
Returns targets associated with host `id`.
/iscsi/host/get_targets
| Name | Description |
|---|---|
| body |
Update iSCSI host `id`.
/iscsi/host/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/iscsi/host/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update iSCSI host `id`.
/iscsi/host/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Creates iSCSI host. `ip` indicates an IP address of the host. `description` is a human-readable name for the host. `iqns` is a list of initiator iSCSI Qualified Names.
/iscsi/host
| Name | Description |
|---|---|
| body |
Associates initiator groups `ids` with host `id`. Use `force` if you want to allow adding first or removing last initiator from initiator groups.
/iscsi/host/set_initiators
| Name | Description |
|---|---|
| body |
Associates targets `ids` with host `id`.
/iscsi/host/set_targets
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/iscsi/initiator
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete iSCSI initiator of `id`.
/iscsi/initiator/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/iscsi/initiator/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update iSCSI initiator of `id`.
/iscsi/initiator/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create an iSCSI Initiator. `initiators` is a list of initiator hostnames which are authorized to access an iSCSI Target. To allow all possible initiators, `initiators` can be left empty. `auth_network` is a list of IP/CIDR addresses which are allowed to use this initiator. If all networks are to be allowed, this field should be left empty.
/iscsi/initiator
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/iscsi/portal
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete iSCSI Portal `id`.
/iscsi/portal/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/iscsi/portal/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update iSCSI Portal `id`.
/iscsi/portal/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Returns possible choices for `listen.ip` attribute of portal create and update.
/iscsi/portal/listen_ip_choices
Create a new iSCSI Portal. `discovery_authgroup` is required for CHAP and CHAP_MUTUAL.
/iscsi/portal
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/iscsi/target
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete iSCSI Target of `id`. Deleting an iSCSI Target makes sure we delete all Associated Targets which use `id` iSCSI Target.
/iscsi/target/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/iscsi/target/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update iSCSI Target of `id`.
/iscsi/target/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create an iSCSI Target. `groups` is a list of group dictionaries which provide information related to using a `portal`, `initiator`, `authmethod` and `auth` with this target. `auth` represents a valid iSCSI Authorized Access and defaults to null.
/iscsi/target
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/iscsi/targetextent
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete Associated Target of `id`.
/iscsi/targetextent/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/iscsi/targetextent/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update Associated Target of `id`.
/iscsi/targetextent/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create an Associated Target. `lunid` will be automatically assigned if it is not provided based on the `target`.
/iscsi/targetextent
| Name | Description |
|---|---|
| body |
/kerberos
`appdefaults_aux` add parameters to "appdefaults" section of the krb5.conf file. `libdefaults_aux` add parameters to "libdefaults" section of the krb5.conf file.
/kerberos
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/kerberos/keytab
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete kerberos keytab by id, and force regeneration of system keytab.
/kerberos/keytab/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/kerberos/keytab/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update kerberos keytab by id.
/kerberos/keytab/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create a kerberos keytab. Uploaded keytab files will be merged with the system keytab under /etc/krb5.keytab. `file` b64encoded kerberos keytab `name` name for kerberos keytab
/kerberos/keytab
| Name | Description |
|---|---|
| body |
Returns content of system keytab (/etc/krb5.keytab).
/kerberos/keytab/system_keytab_list
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/kerberos/realm
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete a kerberos realm by ID.
/kerberos/realm/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/kerberos/realm/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update a kerberos realm by id. This will be automatically populated during the domain join process in an Active Directory environment. Kerberos realm names are case-sensitive, but convention is to only use upper-case.
/kerberos/realm/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create a new kerberos realm. This will be automatically populated during the domain join process in an Active Directory environment. Kerberos realm names are case-sensitive, but convention is to only use upper-case. Entries for kdc, admin_server, and kpasswd_server are not required. If they are unpopulated, then kerberos will use DNS srv records to discover the correct servers. The option to hard-code them is provided due to AD site discovery. Kerberos has no concept of Active Directory sites. This means that middleware performs the site discovery and sets the kerberos configuration based on the AD site.
/kerberos/realm
| Name | Description |
|---|---|
| body |
Generate a public/private key pair Generate a public/private key pair (useful for `SSH_KEY_PAIR` type)
/keychaincredential/generate_ssh_key_pair
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/keychaincredential
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete Keychain Credential with specific `id`
/keychaincredential/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/keychaincredential/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update a Keychain Credential with specific `id` Please note that you can't change `type` Also you must specify full `attributes` value See the documentation for `create` method for information on payload contents
/keychaincredential/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create a Keychain Credential Create a Keychain Credential of any type. Every Keychain Credential has a `name` which is used to distinguish it from others. The following `type`s are supported: * `SSH_KEY_PAIR` Which `attributes` are: * `private_key` * `public_key` (which can be omitted and thus automatically derived from private key) At least one attribute is required. * `SSH_CREDENTIALS` Which `attributes` are: * `host` * `port` (default 22) * `username` (default root) * `private_key` (Keychain Credential ID) * `remote_host_key` (you can use `keychaincredential.remote_ssh_host_key_scan` do discover it) * `cipher`: one of `STANDARD`, `FAST`, or `DISABLED` (last requires special support from both SSH server and client) * `connect_timeout` (default 10)
/keychaincredential
| Name | Description |
|---|---|
| body |
Discover a remote host key Discover a remote host key (useful for `SSH_CREDENTIALS`)
/keychaincredential/remote_ssh_host_key_scan
| Name | Description |
|---|---|
| body |
Perform semi-automatic SSH connection setup with other FreeNAS machine Perform semi-automatic SSH connection setup with other FreeNAS machine. It creates a `SSH_CREDENTIALS` credential with specified `name` that can be used to connect to FreeNAS machine with specified `url` and temporary auth `token`. Other FreeNAS machine adds `private_key` to allowed `username`'s private keys. Other `SSH_CREDENTIALS` attributes such as `cipher` and `connect_timeout` can be specified as well.
/keychaincredential/remote_ssh_semiautomatic_setup
| Name | Description |
|---|---|
| body |
Creates a SSH Connection performing the following steps: 1) Generating SSH Key Pair if required 2) Setting up SSH Credentials based on `setup_type` In case (2) fails, it will be ensured that SSH Key Pair generated ( if applicable ) in the process is removed.
/keychaincredential/setup_ssh_connection
| Name | Description |
|---|---|
| body |
Returns list of objects that use this credential.
/keychaincredential/used_by
| Name | Description |
|---|---|
| body |
Clear all keys which are pending to be synced between KMIP server and TN database. For ZFS/SED keys, we remove the UID from local database with which we are able to retrieve ZFS/SED keys. It should be used with caution.
/kmip/clear_sync_pending_keys
/kmip
Returns true or false based on if there are keys which are to be synced from local database to remote KMIP server or vice versa.
/kmip/kmip_sync_pending
Update KMIP Server Configuration. System currently authenticates connection with remote KMIP Server with a TLS handshake. `certificate` and `certificate_authority` determine the certs which will be used to initiate the TLS handshake with `server`. `validate` is enabled by default. When enabled, system will test connection to `server` making sure it's reachable. `manage_zfs_keys`/`manage_sed_disks` when enabled will sync keys from local database to remote KMIP server. When disabled, if there are any keys left to be retrieved from the KMIP server, it will sync them back to local database. `enabled` if true, cannot be set to disabled if there are existing keys pending to be synced. However users can still perform this action by enabling `force_clear`. `change_server` is a boolean field which allows users to migrate data between two KMIP servers. System will first migrate keys from old KMIP server to local database and then migrate the keys from local database to new KMIP server. If it is unable to retrieve all the keys from old server, this will fail. Users can bypass this by enabling `force_clear`. `force_clear` is a boolean option which when enabled will in this case remove all pending keys to be synced from database. It should be used with extreme caution as users may end up with not having ZFS dataset or SED disks keys leaving them locked forever. It is disabled by default.
/kmip
| Name | Description |
|---|---|
| body |
Sync ZFS/SED keys between KMIP Server and TN database.
/kmip/sync_keys
Create a backup of existing chart releases. The backup will save helm configuration with history for each chart release and then take a snapshot of `ix-applications` dataset.
/kubernetes/backup_chart_releases
| Name | Description |
|---|---|
| body |
Returns ip choices for Kubernetes service to use.
/kubernetes/bindip_choices
Delete `backup_name` chart releases backup.
/kubernetes/delete_backup
| Name | Description |
|---|---|
| body |
Returns events for kubernetes node.
/kubernetes/events
/kubernetes
List existing chart releases backups.
/kubernetes/list_backups
Returns IP used by kubernetes which kubernetes uses to allow incoming connections.
/kubernetes/node_ip
`pool` must be a valid ZFS pool configured in the system. Kubernetes service will initialise the pool by creating datasets under `pool_name/ix-applications`. `configure_gpus` is a boolean to enable or disable to prevent automatically loading any GPU Support into kubernetes. This includes not loading any daemonsets for Intel and NVIDIA support. `servicelb` is a boolean to enable or disable the integrated k3s Service Loadbalancer called "Klipper". This can be set to disabled to enable the user to run another LoadBalancer or no LoadBalancer at all. `cluster_cidr` is the CIDR to be used for default NAT network between workloads. `service_cidr` is the CIDR to be used for kubernetes services which are an abstraction and refer to a logically set of kubernetes pods. `cluster_dns_ip` is the IP of the DNS server running for the kubernetes cluster. It must be in the range of `service_cidr`. Specifying values for `cluster_cidr`, `service_cidr` and `cluster_dns_ip` are permanent and a subsequent change requires re-initialisation of the applications. To clarify, system will destroy old `ix-applications` dataset and any data within it when any of the values for the above configuration change. `node_ip` is the IP address which the kubernetes cluster will assign to the TrueNAS node. It defaults to 0.0.0.0 and the cluster in this case will automatically manage which IP address to use for managing traffic for default NAT network. By default kubernetes pods will be using default gateway of the system for outward traffic. This might not be desirable for certain users who want to separate NAT traffic over a specific interface / route. System will create a L3 network which will be routing the traffic towards default gateway for NAT. If users want to restrict traffic over a certain gateway / interface, they can specify a default route for the NAT traffic. `route_v4_interface` and `route_v4_gateway` will set a default route for the kubernetes cluster IPv4 traffic. Similarly `route_v6_interface` and 'route_v6_gateway` can be used to specify default route for IPv6 traffic. In case user is switching pools and the new desired pool has not been configured for kubernetes before, it is possible to replicate data from old pool to new pool with setting `migrate_applications` attribute. This will replicate contents of old pool's ix-applications dataset to the new pool.
/kubernetes
| Name | Description |
|---|---|
| body |
Restore `backup_name` chart releases backup. It should be noted that a rollback will be initiated which will destroy any newer snapshots/clones of `ix-applications` dataset then the snapshot in question of `backup_name`.
/kubernetes/restore_backup
| Name | Description |
|---|---|
| body |
Returns Interface choices for Kubernetes service to use for ipv4 connections.
/kubernetes/route_interface_choices
/ldap
Wrapper function for 'directoryservices.get_state'. Returns only the state of the LDAP service.
/ldap/get_state
`hostname` list of ip addresses or hostnames of LDAP servers with which to communicate in order of preference. Failover only occurs if the current LDAP server is unresponsive. `basedn` specifies the default base DN to use when performing ldap operations. The base must be specified as a Distinguished Name in LDAP format. `binddn` specifies the default bind DN to use when performing ldap operations. The bind DN must be specified as a Distinguished Name in LDAP format. `anonbind` use anonymous authentication. `ssl` establish SSL/TLS-protected connections to the LDAP server(s). GSSAPI signing is disabled on SSL/TLS-protected connections if kerberos authentication is used. `certificate` LDAPs client certificate to be used for certificate- based authentication. `validate_certificates` specifies whether to perform checks on server certificates in a TLS session. If enabled, TLS_REQCERT demand is set. The server certificate is requested. If no certificate is provided or if a bad certificate is provided, the session is immediately terminated. If disabled, TLS_REQCERT allow is set. The server certificate is requested, but all errors are ignored. `kerberos_realm` in which the server is located. This parameter is only required for SASL GSSAPI authentication to the remote LDAP server. `kerberos_principal` kerberos principal to use for SASL GSSAPI authentication to the remote server. If `kerberos_realm` is specified without a keytab, then the `binddn` and `bindpw` are used to perform to obtain the ticket necessary for GSSAPI authentication. `timeout` specifies a timeout (in seconds) after which calls to synchronous LDAP APIs will abort if no response is received. `dns_timeout` specifies the timeout (in seconds) after which the poll(2)/select(2) following a connect(2) returns in case of no activity for openldap. For nslcd this specifies the time limit (in seconds) to use when connecting to the directory server. This directly impacts the length of time that the LDAP service tries before failing over to a secondary LDAP URI. `has_samba_schema` determines whether to configure samba to use the ldapsam passdb backend to provide SMB access to LDAP users. This feature requires the presence of Samba LDAP schema extensions on the remote LDAP server.
/ldap
| Name | Description |
|---|---|
| body |
Returns list of available LDAP schema choices.
/ldap/schema_choices
Returns list of SSL choices.
/ldap/ssl_choices
Returns country choices for LLDP.
/lldp/country_choices
/lldp
Update LLDP Service Configuration. `country` is a two letter ISO 3166 country code required for LLDP location support. `location` is an optional attribute specifying the physical location of the host.
/lldp
| Name | Description |
|---|---|
| body |
/mail
Update Mail Service Configuration. `fromemail` is used as a sending address which the mail server will use for sending emails. `outgoingserver` is the hostname or IP address of SMTP server used for sending an email. `security` is type of encryption desired. `smtp` is a boolean value which when set indicates that SMTP authentication has been enabled and `user`/`pass` are required attributes now.
/mail
| Name | Description |
|---|---|
| body |
Sends mail using configured mail settings. `text` will be formatted to HTML using Markdown and rendered using default E-Mail template. You can put your own HTML using `html`. If `html` is null, no HTML MIME part will be added to E-Mail. If `attachments` is true, a list compromised of the following dict is required via HTTP upload: - headers(list) - name(str) - value(str) - params(dict) - content (str) [ { "headers": [ { "name": "Content-Transfer-Encoding", "value": "base64" }, { "name": "Content-Type", "value": "application/octet-stream", "params": { "name": "test.txt" } } ], "content": "dGVzdAo=" } ] A file can be uploaded to this end point. This end point is special, please refer to Jobs section in Websocket API documentation for details.
/mail/send
| Name | Description |
|---|---|
| body |
Returns allowed/forbidden network activity choices.
/network/configuration/activity_choices
/network/configuration
Update Network Configuration Service configuration. `ipv4gateway` if set is used instead of the default gateway provided by DHCP. `nameserver1` is primary DNS server. `nameserver2` is secondary DNS server. `nameserver3` is tertiary DNS server. `httpproxy` attribute must be provided if a proxy is to be used for network operations. `netwait_enabled` is a boolean attribute which when set indicates that network services will not start at boot unless they are able to ping the addresses listed in `netwait_ip` list. `service_announcement` determines the broadcast protocols that will be used to advertise the server. `netbios` enables the NetBIOS name server (NBNS), which starts concurrently with the SMB service. SMB clients will only perform NBNS lookups if SMB1 is enabled. NBNS may be required for legacy SMB clients. `mdns` enables multicast DNS service announcements for enabled services. `wsd` enables Web Service Discovery support.
/network/configuration
| Name | Description |
|---|---|
| body |
Retrieve general information for current Network. Returns a dictionary. For example:
/network/general/summary
Use user-provided admin credentials to kinit, add NFS SPN entries to the remote kerberos server, and then append the new entries to our system keytab. Currently this is only supported in AD environments.
/nfs/add_principal
| Name | Description |
|---|---|
| body |
Returns ip choices for NFS service to use
/nfs/bindip_choices
Return currently connected clients count. Count may not be accurate if NFSv3 protocol is in use due to potentially stale rmtab entries.
/nfs/client_count
/nfs
Update NFS Service Configuration. `servers` represents number of servers to create. When `allow_nonroot` is set, it allows non-root mount requests to be served. `bindip` is a list of IP's on which NFS will listen for requests. When it is unset/empty, NFS listens on all available addresses. `v4` when set means that we switch from NFSv3 to NFSv4. `v4_v3owner` when set means that system will use NFSv3 ownership model for NFSv4. `v4_krb` will force NFS shares to fail if the Kerberos ticket is unavailable. `v4_domain` overrides the default DNS domain name for NFSv4. `mountd_port` specifies the port mountd(8) binds to. `rpcstatd_port` specifies the port rpc.statd(8) binds to. `rpclockd_port` specifies the port rpclockd_port(8) binds to.
/nfs
| Name | Description |
|---|---|
| body |
Returns a dictionary of valid authentication algorithms which can be used with OpenVPN server.
/openvpn/client/authentication_algorithm_choices
Returns a dictionary of valid ciphers which can be used with OpenVPN server.
/openvpn/client/cipher_choices
/openvpn/client
Update OpenVPN Client configuration. `remote` can be a valid ip address / domain which openvpn will try to connect to. `nobind` must be enabled if OpenVPN client / server are to run concurrently.
/openvpn/client
| Name | Description |
|---|---|
| body |
Returns a dictionary of valid authentication algorithms which can be used with OpenVPN server.
/openvpn/server/authentication_algorithm_choices
Returns a dictionary of valid ciphers which can be used with OpenVPN server.
/openvpn/server/cipher_choices
Returns a configuration for OpenVPN client which can be used with any client to connect to FN/TN OpenVPN server. `client_certificate_id` should be a valid certificate issued for use with OpenVPN client service. `server_address` if specified auto-fills the remote directive in the OpenVPN configuration enabling the end user to use the file without making any edits to connect to OpenVPN server.
/openvpn/server/client_configuration_generation
| Name | Description |
|---|---|
| body |
/openvpn/server
Update OpenVPN Server configuration. When `tls_crypt_auth_enabled` is enabled and `tls_crypt_auth` not provided, a static key is automatically generated to be used with OpenVPN server.
/openvpn/server
| Name | Description |
|---|---|
| body |
Reset OpenVPN server's TLS static key which will be used to encrypt/authenticate control channel packets.
/openvpn/server/renew_static_key
For TrueNAS Core/Enterprise platform, if the `oid` pool is passphrase GELI encrypted, `passphrase` must be specified for this operation to succeed. `target_vdev` is the GUID of the vdev where the disk needs to be attached. In case of STRIPED vdev, this is the STRIPED disk GUID which will be converted to mirror. If `target_vdev` is mirror, it will be converted into a n-way mirror.
/pool/attach
| Name | Description |
|---|---|
| body |
Returns all available datasets, except the following: 1. system datasets 2. glusterfs datasets 3. application(s) internal datasets
/pool/filesystem_choices
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/pool
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Returns pool with name `name`. If `name` is not found, Validation error is raised.
/pool/get_instance_by_name
| Name | Description |
|---|---|
| body |
Return a list of services dependent of this pool. Responsible for telling the user whether there is a related share, asking for confirmation.
/pool/id/{id}/attachments
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Detach a disk from pool of id `id`. `label` is the vdev guid or device name.
/pool/id/{id}/detach
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Expand pool to fit all available disk space.
/pool/id/{id}/expand
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Export pool of `id`. `cascade` will delete all attachments of the given pool (`pool.attachments`). `restart_services` will restart services that have open files on given pool. `destroy` will also PERMANENTLY destroy the pool/data.
/pool/id/{id}/export
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/pool/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Get all disks in use by pools. If `id` is provided only the disks from the given pool `id` will be returned.
/pool/id/{id}/get_disks
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Returns whether or not the pool of `id` is on the latest version and with all feature flags enabled.
/pool/id/{id}/is_upgraded
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Offline a disk from pool of id `id`. `label` is the vdev guid or device name.
/pool/id/{id}/offline
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Online a disk from pool of id `id`. `label` is the vdev guid or device name.
/pool/id/{id}/online
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Returns a list of running processes using this pool.
/pool/id/{id}/processes
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update pool of `id`, adding the new topology. The `type` of `data` must be the same of existing vdevs.
/pool/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Remove a disk from pool of id `id`. `label` is the vdev guid or device name. Error codes: EZFS_NOSPC(2032): out of space to remove a device EZFS_NODEVICE(2017): no such device in pool EZFS_NOREPLICAS(2019): no valid replicas
/pool/id/{id}/remove
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Replace a disk on a pool. `label` is the ZFS guid or a device name `disk` is the identifier of a disk `passphrase` is only valid for TrueNAS Core/Enterprise platform where pool is GELI encrypted If `preserve_settings` is true, then settings (power management, S.M.A.R.T., etc.) of a disk being replaced will be applied to a new disk.
/pool/id/{id}/replace
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Performs a scrub action to pool of `id`. `action` can be either of "START", "STOP" or "PAUSE".
/pool/id/{id}/scrub
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Upgrade pool of `id` to latest version with all feature flags.
/pool/id/{id}/upgrade
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Autodetect filesystem type for `pool.import_disk`.
/pool/import_disk_autodetect_fs_type
| Name | Description |
|---|---|
| body |
Get a list of locales for msdosfs type to be used in `pool.import_disk`.
/pool/import_disk_msdosfs_locales
Import a disk, by copying its content to a pool.
/pool/import_disk
| Name | Description |
|---|---|
| body |
Returns a job id which can be used to retrieve a list of pools available for import with the following details as a result of the job: name, guid, status, hostname.
/pool/import_find
Import a pool found with `pool.import_find`. If a `name` is specified the pool will be imported using that new name. `passphrase` DEPRECATED. GELI not supported on SCALE. If `enable_attachments` is set to true, attachments that were disabled during pool export will be re-enabled. Errors: ENOENT - Pool not found
/pool/import_pool
| Name | Description |
|---|---|
| body |
Create a new ZFS Pool. `topology` is a object which requires at least one `data` entry. All of `data` entries (vdevs) require to be of the same type. `deduplication` when set to ON or VERIFY makes sure that no block of data is duplicated in the pool. When VERIFY is specified, if two blocks have similar signatures, byte to byte comparison is performed to ensure that the blocks are identical. This should be used in special circumstances as it carries a significant overhead. `encryption` when enabled will create an ZFS encrypted root dataset for `name` pool. `encryption_options` specifies configuration for encryption of root dataset for `name` pool. `encryption_options.passphrase` must be specified if encryption for root dataset is desired with a passphrase as a key. Otherwise a hex encoded key can be specified by providing `encryption_options.key`. `encryption_options.generate_key` when enabled automatically generates the key to be used for dataset encryption. It should be noted that keys are stored by the system for automatic locking/unlocking on import/export of encrypted datasets. If that is not desired, dataset should be created with a passphrase as a key. Example of `topology`: { "data": [ {"type": "RAIDZ1", "disks": ["da1", "da2", "da3"]} ], "cache": [ {"type": "STRIPE", "disks": ["da4"]} ], "log": [ {"type": "STRIPE", "disks": ["da5"]} ], "spares": ["da6"] }
/pool
| Name | Description |
|---|---|
| body |
Change encryption properties for `id` encrypted dataset. Changing dataset encryption to use passphrase instead of a key is not allowed if: 1) It has encrypted roots as children which are encrypted with a key 2) If it is a root dataset where the system dataset is located A file can be uploaded to this end point. This end point is special, please refer to Jobs section in Websocket API documentation for details.
/pool/dataset/change_key
| Name | Description |
|---|---|
| body |
Retrieve checksums supported for ZFS dataset.
/pool/dataset/checksum_choices
Retrieve compression algorithm supported by ZFS.
/pool/dataset/compression_choices
Destroy specified snapshots of a given dataset.
/pool/dataset/destroy_snapshots
| Name | Description |
|---|---|
| body |
Retrieve encryption algorithms supported for ZFS dataset encryption.
/pool/dataset/encryption_algorithm_choices
Retrieve summary of all encrypted roots under `id`. Keys/passphrase can be supplied to check if the keys are valid. It should be noted that there are 2 keys which show if a recursive unlock operation is done for `id`, which dataset will be unlocked and if not why it won't be unlocked. The keys namely are "unlock_successful" and "unlock_error". The former is a boolean value showing if unlock would succeed/fail. The latter is description why it failed if it failed. In some cases it's possible that the provided key/passphrase is valid but the path where the dataset is supposed to be mounted after being unlocked already exists and is not empty. In this case, unlock operation would fail and `unlock_error` will reflect this error appropriately. This can be overridden by setting `encryption_root_summary_options.datasets.X.force` boolean flag or by setting `encryption_root_summary_options.force` flag. In practice, when the dataset is going to be unlocked and these flags have been provided to `pool.dataset.unlock`, system will rename the directory/file path where the dataset should be mounted resulting in successful unlock of the dataset. If a dataset is already unlocked, it will show up as true for "unlock_successful" regardless of what key user provided as the unlock keys in the output are to reflect what a real unlock operation would behave. If user is interested in seeing if a provided key is valid or not, then the key to look out for in the output is "valid_key" which based on what system has in database or if a user provided one, validates the key and sets a boolean value for the dataset. Example output: [ { "name": "vol", "key_format": "PASSPHRASE", "key_present_in_database": false, "valid_key": true, "locked": true, "unlock_error": null, "unlock_successful": true }, { "name": "vol/c1/d1", "key_format": "PASSPHRASE", "key_present_in_database": false, "valid_key": false, "locked": true, "unlock_error": "Provided key is invalid", "unlock_successful": false }, { "name": "vol/c", "key_format": "PASSPHRASE", "key_present_in_database": false, "valid_key": false, "locked": true, "unlock_error": "Key not provided", "unlock_successful": false }, { "name": "vol/c/d2", "key_format": "PASSPHRASE", "key_present_in_database": false, "valid_key": false, "locked": true, "unlock_error": "Child cannot be unlocked when parent "vol/c" is locked and provided key is invalid", "unlock_successful": false } ] A file can be uploaded to this end point. This end point is special, please refer to Jobs section in Websocket API documentation for details.
/pool/dataset/encryption_summary
| Name | Description |
|---|---|
| body |
Export own encryption key for dataset `id`. If `download` is `true`, key will be downloaded in a json file where the same file can be used to unlock the dataset, otherwise it will be returned as string. Please refer to websocket documentation for downloading the file. A file can be downloaded from this end point. This end point is special, please refer to Jobs section in Websocket API documentation for details.
/pool/dataset/export_key
| Name | Description |
|---|---|
| body |
Query Pool Datasets with `query-filters` and `query-options`. We provide two ways to retrieve datasets. The first is a flat structure (default), where all datasets in the system are returned as separate objects which contain all data there is for their children. This retrieval type is slightly slower because of duplicates in each object. The second type is hierarchical, where only top level datasets are returned in the list. They contain all the children in the `children` key. This retrieval type is slightly faster. These options are controlled by the `query-options.extra.flat` attribute (default true). In some cases it might be desirable to only retrieve details of a dataset itself and not it's children, in this case `query-options.extra.retrieve_children` should be explicitly specified and set to `false` which will result in children not being retrieved. In case only some properties are desired to be retrieved for datasets, consumer should specify `query-options.extra.properties` which when `null` ( which is the default ) will retrieve all properties and otherwise a list can be specified like `["type", "used", "available"]` to retrieve selective properties. If no properties are desired, in that case an empty list should be sent. `query-options.extra.snapshots` can be set to retrieve snapshot(s) of dataset in question. `query-options.extra.snapshots_recursive` can be set to retrieve snapshot(s) recursively of dataset in question. If `query-options.extra.snapshots_recursive` and `query-options.extra.snapshots` are set, snapshot(s) will be retrieved recursively. `query-options.extra.snapshots_properties` can be specified to list out properties which should be retrieved for snapshot(s) related to each dataset. By default only name of the snapshot would be retrieved, however if `null` is specified all properties of the snapshot would be retrieved in this case. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/pool/dataset
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Return a list of services dependent of this dataset. Responsible for telling the user whether there is a related share, asking for confirmation. Example return value: [ { "type": "NFS Share", "service": "nfs", "attachments": ["/mnt/tank/work"] } ]
/pool/dataset/id/{id}/attachments
| Name | Description |
|---|---|
| id* |
String
Required
|
Delete dataset/zvol `id`. `recursive` will also delete/destroy all children datasets. `force` will force delete busy datasets.
/pool/dataset/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Query Pool Datasets with `query-filters` and `query-options`. We provide two ways to retrieve datasets. The first is a flat structure (default), where all datasets in the system are returned as separate objects which contain all data there is for their children. This retrieval type is slightly slower because of duplicates in each object. The second type is hierarchical, where only top level datasets are returned in the list. They contain all the children in the `children` key. This retrieval type is slightly faster. These options are controlled by the `query-options.extra.flat` attribute (default true). In some cases it might be desirable to only retrieve details of a dataset itself and not it's children, in this case `query-options.extra.retrieve_children` should be explicitly specified and set to `false` which will result in children not being retrieved. In case only some properties are desired to be retrieved for datasets, consumer should specify `query-options.extra.properties` which when `null` ( which is the default ) will retrieve all properties and otherwise a list can be specified like `["type", "used", "available"]` to retrieve selective properties. If no properties are desired, in that case an empty list should be sent. `query-options.extra.snapshots` can be set to retrieve snapshot(s) of dataset in question. `query-options.extra.snapshots_recursive` can be set to retrieve snapshot(s) recursively of dataset in question. If `query-options.extra.snapshots_recursive` and `query-options.extra.snapshots` are set, snapshot(s) will be retrieved recursively. `query-options.extra.snapshots_properties` can be specified to list out properties which should be retrieved for snapshot(s) related to each dataset. By default only name of the snapshot would be retrieved, however if `null` is specified all properties of the snapshot would be retrieved in this case. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/pool/dataset/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Return a list of the specified `quota_type` of quotas on the ZFS dataset `ds`. Support `query-filters` and `query-options`. used_bytes and used_percentage may not instantly update as space is used. When quota_type is not DATASET, each quota entry has these fields: `id` - the uid or gid to which the quota applies. `name` - the user or group name to which the quota applies. Value is null if the id in the quota cannot be resolved to a user or group. This indicates that the user or group does not exist on the server. `quota` - the quota size in bytes. `used_bytes` - the amount of bytes the user has written to the dataset. A value of zero means unlimited. `used_percentage` - the percentage of the user or group quota consumed. `obj_quota` - the number of objects that may be owned by `id`. A value of zero means unlimited. 'obj_used` - the nubmer of objects currently owned by `id`. `obj_used_percent` - the percentage of the `obj_quota` currently used. Note: SMB client requests to set a quota granting no space will result in an on-disk quota of 1 KiB.
/pool/dataset/id/{id}/get_quota
| Name | Description |
|---|---|
| id* |
String
Required
|
Set permissions for a dataset `id`. Permissions may be specified as either a posix `mode` or an `acl`. This method is a wrapper around `filesystem.setperm`, `filesystem.setacl`, and `filesystem.chown` `filesystem.setperm` is called if `mode` is specified. `filesystem.setacl` is called if `acl` is specified or if the option `set_default_acl` is selected. `filesystem.chown` is called if neither `mode` nor `acl` is specified. The following `options` are supported: `set_default_acl` - apply a default ACL appropriate for specified dataset. Default ACL is `NFS4_RESTRICTED` or `POSIX_RESTRICTED` ACL template builtin with additional entries builtin_users group and builtin_administrators group. See documentation for `filesystem.acltemplate` for more details. `stripacl` - this option must be set in order to apply a POSIX mode to a dataset that has a non-trivial ACL. The effect will be to remove existing ACL and replace with specified mode. `recursive` - apply permissions recursively to dataset (all files and directories will be impacted. `traverse` - permit recursive job to traverse filesystem boundaries (child datasets).
/pool/dataset/id/{id}/permission
| Name | Description |
|---|---|
| id* |
String
Required
|
Return a list of processes using this dataset. Example return value: [ { "pid": 2520, "name": "smbd", "service": "cifs" }, { "pid": 97778, "name": "minio", "cmdline": "/usr/local/bin/minio -C /usr/local/etc/minio server --address=0.0.0.0:9000 --quiet /mnt/tank/wk" } ]
/pool/dataset/id/{id}/processes
| Name | Description |
|---|---|
| id* |
String
Required
|
Promote the cloned dataset `id`.
/pool/dataset/id/{id}/promote
| Name | Description |
|---|---|
| id* |
String
Required
|
Updates a dataset/zvol `id`.
/pool/dataset/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
There are three over-arching types of quotas for ZFS datasets. 1) dataset quotas and refquotas. If a DATASET quota type is specified in this API call, then the API acts as a wrapper for `pool.dataset.update`. 2) User and group quotas. These limit the amount of disk space consumed by files that are owned by the specified users or groups. If the respective "object quota" type is specfied, then the quota limits the number of objects that may be owned by the specified user or group. 3) Project quotas. These limit the amount of disk space consumed by files that are owned by the specified project. Project quotas are not yet implemended. This API allows users to set multiple quotas simultaneously by submitting a list of quotas. The list may contain all supported quota types. `ds` the name of the target ZFS dataset. `quotas` specifies a list of `quota_entry` entries to apply to dataset. `quota_entry` entries have these required parameters: `quota_type`: specifies the type of quota to apply to the dataset. Possible values are USER, USEROBJ, GROUP, GROUPOBJ, and DATASET. USEROBJ and GROUPOBJ quotas limit the number of objects consumed by the specified user or group. `id`: the uid, gid, or name to which the quota applies. If quota_type is 'DATASET', then `id` must be either `QUOTA` or `REFQUOTA`. `quota_value`: the quota size in bytes. Setting a value of `0` removes the user or group quota.
/pool/dataset/id/{id}/set_quota
| Name | Description |
|---|---|
| id* |
String
Required
|
Allows inheriting parent's encryption root discarding its current encryption settings. This can only be done where `id` has an encrypted parent and `id` itself is an encryption root.
/pool/dataset/inherit_parent_encryption_properties
| Name | Description |
|---|---|
| body |
Locks `id` dataset. It will unmount the dataset and its children before locking. After the dataset has been unmounted, system will set immutable flag on the dataset's mountpoint where the dataset was mounted before it was locked making sure that the path cannot be modified. Once the dataset is unlocked, it will not be affected by this change and consumers can continue consuming it.
/pool/dataset/lock
| Name | Description |
|---|---|
| body |
Creates a dataset/zvol. `volsize` is required for type=VOLUME and is supposed to be a multiple of the block size. `sparse` and `volblocksize` are only used for type=VOLUME. `encryption` when enabled will create an ZFS encrypted root dataset for `name` pool. There are 2 cases where ZFS encryption is not allowed for a dataset: 1) Pool in question is GELI encrypted. 2) If the parent dataset is encrypted with a passphrase and `name` is being created with a key for encrypting the dataset. `encryption_options` specifies configuration for encryption of dataset for `name` pool. `encryption_options.passphrase` must be specified if encryption for dataset is desired with a passphrase as a key. Otherwise a hex encoded key can be specified by providing `encryption_options.key`. `encryption_options.generate_key` when enabled automatically generates the key to be used for dataset encryption. It should be noted that keys are stored by the system for automatic locking/unlocking on import/export of encrypted datasets. If that is not desired, dataset should be created with a passphrase as a key.
/pool/dataset
| Name | Description |
|---|---|
| body |
Helper method to get recommended size for a new zvol (dataset of type VOLUME).
/pool/dataset/recommended_zvol_blocksize
| Name | Description |
|---|---|
| body |
Unlock `id` dataset. If `id` dataset is not encrypted an exception will be raised. There is one exception: when `id` is a root dataset and `unlock_options.recursive` is specified, encryption validation will not be performed for `id`. This allow unlocking encrypted children the `id` pool. For datasets which are encrypted with a passphrase, include the passphrase with `unlock_options.datasets`. Uploading a json file which contains encrypted dataset keys can be specified with `unlock_options.key_file`. The format is similar to that used for exporting encrypted dataset keys. `toggle_attachments` controls whether attachments should be put in action after unlocking dataset(s). Toggling attachments can theoretically lead to service interruption when daemons configurations are reloaded (this should not happen, and if this happens it should be considered a bug). As TrueNAS does not have a state for resources that should be unlocked but are still locked, disabling this option will put the system into an inconsistent state so it should really never be disabled. In some cases it's possible that the provided key/passphrase is valid but the path where the dataset is supposed to be mounted after being unlocked already exists and is not empty. In this case, unlock operation would fail. This can be overridden by setting `unlock_options.datasets.X.force` boolean flag or by setting `unlock_options.force` flag. When any of these flags are set, system will rename the existing directory/file path where the dataset should be mounted resulting in successful unlock of the dataset. A file can be uploaded to this end point. This end point is special, please refer to Jobs section in Websocket API documentation for details.
/pool/dataset/unlock
| Name | Description |
|---|---|
| body |
Get a mapping of services identifiers and labels that can be restart on dataset unlock.
/pool/dataset/unlock_services_restart_choices
| Name | Description |
|---|---|
| body |
Query all user properties for ZFS datasets. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/pool/dataset/userprop
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete user property `dataset_user_prop_delete.name` for `id` dataset.
/pool/dataset/userprop/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Query all user properties for ZFS datasets. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/pool/dataset/userprop/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Update `dataset_user_prop_update.name` user property for `id` dataset.
/pool/dataset/userprop/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Create a user property for a given `id` dataset.
/pool/dataset/userprop
| Name | Description |
|---|---|
| body |
/pool/resilver
Configure Pool Resilver Priority. If `begin` time is greater than `end` time it means it will rollover the day, e.g. begin = "19:00", end = "05:00" will increase pool resilver priority from 19:00 of one day until 05:00 of the next day. `weekday` follows crontab(5) values 0-7 (0 or 7 is Sun).
/pool/resilver
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/pool/scrub
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete scrub task of `id`.
/pool/scrub/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/pool/scrub/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update scrub task of `id`.
/pool/scrub/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create a scrub task for a pool. `threshold` refers to the minimum amount of time in days has to be passed before a scrub can run again.
/pool/scrub
| Name | Description |
|---|---|
| body |
Initiate a scrub of a pool `name` if last scrub was performed more than `threshold` days before.
/pool/scrub/run
| Name | Description |
|---|---|
| body |
Start/Stop/Pause a scrub on pool `name`.
/pool/scrub/scrub
| Name | Description |
|---|---|
| body |
Returns a number of snapshots (per-dataset) being retained if a periodic snapshot task with specific parameters is created.
/pool/snapshottask/foreseen_count
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/pool/snapshottask
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete a Periodic Snapshot Task with specific `id`
/pool/snapshottask/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Returns a list of snapshots which will change the retention if periodic snapshot task `id` is deleted.
/pool/snapshottask/id/{id}/delete_will_change_retention_for
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/pool/snapshottask/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update a Periodic Snapshot Task with specific `id` See the documentation for `create` method for information on payload contents
/pool/snapshottask/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Execute a Periodic Snapshot Task of `id`.
/pool/snapshottask/id/{id}/run
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Returns a list of snapshots which will change the retention if periodic snapshot task `id` is updated with `data`.
/pool/snapshottask/id/{id}/update_will_change_retention_for
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Returns a maximum amount of snapshots (per-dataset) the system can sustain.
/pool/snapshottask/max_count
Create a Periodic Snapshot Task Create a Periodic Snapshot Task that will take snapshots of specified `dataset` at specified `schedule`. Recursive snapshots can be created if `recursive` flag is enabled. You can `exclude` specific child datasets or zvols from the snapshot. Snapshots will be automatically destroyed after a certain amount of time, specified by `lifetime_value` and `lifetime_unit`. If multiple periodic tasks create snapshots at the same time (for example hourly and daily at 00:00) the snapshot will be kept until the last of these tasks reaches its expiry time. Snapshots will be named according to `naming_schema` which is a `strftime`-like template for snapshot name and must contain `%Y`, `%m`, `%d`, `%H` and `%M`.
/pool/snapshottask
| Name | Description |
|---|---|
| body |
Count how many existing snapshots of `dataset` match `naming_schema`.
/replication/count_eligible_manual_snapshots
| Name | Description |
|---|---|
| body |
Creates dataset on remote side Accepts `dataset` name, `transport` and SSH credentials ID (for non-local transport)
/replication/create_dataset
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/replication
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete a Replication Task with specific `id`
/replication/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/replication/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update a Replication Task with specific `id` See the documentation for `create` method for information on payload contents
/replication/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create the opposite of replication task `id` (PULL if it was PUSH and vice versa).
/replication/id/{id}/restore
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Run Replication Task of `id`.
/replication/id/{id}/run
| Name | Description |
|---|---|
| id* |
Integer
Required
|
List datasets on remote side Accepts `transport` and SSH credentials ID (for non-local transport)
/replication/list_datasets
| Name | Description |
|---|---|
| body |
List all naming schemas used in periodic snapshot and replication tasks.
/replication/list_naming_schemas
Create a Replication Task Create a Replication Task that will push or pull ZFS snapshots to or from remote host.. * `name` specifies a name for replication task * `direction` specifies whether task will `PUSH` or `PULL` snapshots * `transport` is a method of snapshots transfer: * `SSH` transfers snapshots via SSH connection. This method is supported everywhere but does not achieve great performance `ssh_credentials` is a required field for this transport (Keychain Credential ID of type `SSH_CREDENTIALS`) * `SSH+NETCAT` uses unencrypted connection for data transfer. This can only be used in trusted networks and requires a port (specified by range from `netcat_active_side_port_min` to `netcat_active_side_port_max`) to be open on `netcat_active_side` `ssh_credentials` is also required for control connection * `LOCAL` replicates to or from localhost * `source_datasets` is a non-empty list of datasets to replicate snapshots from * `target_dataset` is a dataset to put snapshots into. It must exist on target side * `recursive` and `exclude` have the same meaning as for Periodic Snapshot Task * `properties` control whether we should send dataset properties along with snapshots * `periodic_snapshot_tasks` is a list of periodic snapshot task IDs that are sources of snapshots for this replication task. Only push replication tasks can be bound to periodic snapshot tasks. * `naming_schema` is a list of naming schemas for pull replication * `also_include_naming_schema` is a list of naming schemas for push replication * `name_regex` will replicate all snapshots which names match specified regular expression * `auto` allows replication to run automatically on schedule or after bound periodic snapshot task * `schedule` is a schedule to run replication task. Only `auto` replication tasks without bound periodic snapshot tasks can have a schedule * `restrict_schedule` restricts when replication task with bound periodic snapshot tasks runs. For example, you can have periodic snapshot tasks that run every 15 minutes, but only run replication task every hour. * Enabling `only_matching_schedule` will only replicate snapshots that match `schedule` or `restrict_schedule` * `allow_from_scratch` will destroy all snapshots on target side and replicate everything from scratch if none of the snapshots on target side matches source snapshots * `readonly` controls destination datasets readonly property: * `SET` will set all destination datasets to readonly=on after finishing the replication * `REQUIRE` will require all existing destination datasets to have readonly=on property * `IGNORE` will avoid this kind of behavior * `hold_pending_snapshots` will prevent source snapshots from being deleted by retention of replication fails for some reason * `retention_policy` specifies how to delete old snapshots on target side: * `SOURCE` deletes snapshots that are absent on source side * `CUSTOM` deletes snapshots that are older than `lifetime_value` and `lifetime_unit` * `NONE` does not delete any snapshots * `compression` compresses SSH stream. Available only for SSH transport * `speed_limit` limits speed of SSH stream. Available only for SSH transport * `large_block`, `embed` and `compressed` are various ZFS stream flag documented in `man zfs send` * `retries` specifies number of retries before considering replication failed
/replication
| Name | Description |
|---|---|
| body |
Run replication task without creating it. If `only_from_scratch` is `true` then replication will fail if target dataset already exists.
/replication/run_onetime
| Name | Description |
|---|---|
| body |
Check if target has any snapshots that do not exist on source. Returns these snapshots grouped by dataset.
/replication/target_unmatched_snapshots
| Name | Description |
|---|---|
| body |
/replication/config
`max_parallel_replication_tasks` represents a maximum number of parallel replication tasks running.
/replication/config
| Name | Description |
|---|---|
| body |
Clear reporting database.
/reporting/clear
/reporting
Get reporting data for given graphs. List of possible graphs can be retrieved using `reporting.graphs` call. For the time period of the graph either `unit` and `page` OR `start` and `end` should be used, not both. `aggregate` will return aggregate available data for each graph (e.g. min, max, mean).
/reporting/get_data
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/reporting/graphs
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Configure Reporting Database settings. If `cpu_in_percentage` is `true`, collectd reports CPU usage in percentage instead of "jiffies". `graphite` specifies a destination hostname or IP for collectd data sent by the Graphite plugin.. `graphite_separateinstances` corresponds to collectd SeparateInstances option. `graph_age` specifies the maximum age of stored graphs in months. `graph_points` is the number of points for each hourly, daily, weekly, etc. graph. Changing these requires destroying the current reporting database, so when these fields are changed, an additional `confirm_rrd_destroy: true` flag must be present.
/reporting
| Name | Description |
|---|---|
| body |
Get the IPv4 gateway and verify if it is reachable by any interface. Returns: bool: True if the gateway is reachable or otherwise False.
/route/ipv4gw_reachable
| Name | Description |
|---|---|
| body |
Get current/applied network routes. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/route/system_routes
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
/rsyncd
Update Rsyncd Service Configuration. `auxiliary` attribute can be used to pass on any additional parameters from rsyncd.conf(5).
/rsyncd
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/rsyncmod
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete Rsyncmod module of `id`.
/rsyncmod/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/rsyncmod/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update Rsyncmod module of `id`.
/rsyncmod/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create a Rsyncmod module. `path` represents the path to a dataset. Path length is limited to 1023 characters maximum as per the limit enforced by FreeBSD. It is possible that we reach this max length recursively while transferring data. In that case, the user must ensure the maximum path will not be too long or modify the recursed path to shorter than the limit. `maxconn` is an integer value representing the maximum number of simultaneous connections. Zero represents unlimited. `hostsallow` is a list of patterns to match hostname/ip address of a connecting client. If list is empty, all hosts are allowed. `hostsdeny` is a list of patterns to match hostname/ip address of a connecting client. If the pattern is matched, access is denied to the client. If no client should be denied, this should be left empty. `auxiliary` attribute can be used to pass on any additional parameters from rsyncd.conf(5).
/rsyncmod
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/rsynctask
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete Rsync Task of `id`.
/rsynctask/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/rsynctask/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update Rsync Task of `id`.
/rsynctask/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Job to run rsync task of `id`. Output is saved to job log excerpt (not syslog).
/rsynctask/id/{id}/run
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create a Rsync Task. See the comment in Rsyncmod about `path` length limits. `remotehost` is ip address or hostname of the remote system. If username differs on the remote host, "username@remote_host" format should be used. `mode` represents different operating mechanisms for Rsync i.e Rsync Module mode / Rsync SSH mode. `remotemodule` is the name of remote module, this attribute should be specified when `mode` is set to MODULE. `remotepath` specifies the path on the remote system. `validate_rpath` is a boolean which when sets validates the existence of the remote path. `direction` specifies if data should be PULLED or PUSHED from the remote system. `compress` when set reduces the size of the data which is to be transmitted. `archive` when set makes rsync run recursively, preserving symlinks, permissions, modification times, group, and special files. `delete` when set deletes files in the destination directory which do not exist in the source directory. `preserveperm` when set preserves original file permissions.
/rsynctask
| Name | Description |
|---|---|
| body |
Return ip choices for S3 service to use.
/s3/bindip_choices
/s3
Update S3 Service Configuration. `access_key` must only contain alphanumeric characters and should be between 5 and 20 characters. `secret_key` must only contain alphanumeric characters and should be between 8 and 40 characters. `browser` when set, enables the web user interface for the S3 Service. `certificate` is a valid certificate id which exists in the system. This is used to enable secure S3 connections.
/s3
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/sensor/query
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Query all system services with `query-filters` and `query-options`. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/service
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Query all system services with `query-filters` and `query-options`. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/service/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update service entry of `id_or_name`. Currently it only accepts `enable` option which means whether the service should start on boot.
/service/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Reload the service specified by `service`.
/service/reload
| Name | Description |
|---|---|
| body |
Restart the service specified by `service`.
/service/restart
| Name | Description |
|---|---|
| body |
Start the service specified by `service`.
/service/start
| Name | Description |
|---|---|
| body |
Test if service specified by `service` is started or enabled to start automatically.
/service/started_or_enabled
| Name | Description |
|---|---|
| body |
Test if service specified by `service` has been started.
/service/started
| Name | Description |
|---|---|
| body |
Stop the service specified by `service`.
/service/stop
| Name | Description |
|---|---|
| body |
Terminate process by `pid`. First send `TERM` signal, then, if was not terminated in `timeout` seconds, send `KILL` signal.
/service/terminate_process
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/sharing/nfs
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete NFS Share of `id`.
/sharing/nfs/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/sharing/nfs/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update NFS Share of `id`.
/sharing/nfs/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create a NFS Share. `paths` is a list of valid paths which are configured to be shared on this share. `aliases` IGNORED, for now. `networks` is a list of authorized networks that are allowed to access the share having format "network/mask" CIDR notation. If empty, all networks are allowed. `hosts` is a list of IP's/hostnames which are allowed to access the share. If empty, all IP's/hostnames are allowed. `alldirs` is a boolean value which when set indicates that the client can mount any subdirectories of the selected pool or dataset.
/sharing/nfs
| Name | Description |
|---|---|
| body |
Query shares with filters. In clustered environments, local datastore query is bypassed in favor of clustered registry. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/sharing/smb
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete SMB Share of `id`. This will forcibly disconnect SMB clients that are accessing the share.
/sharing/smb/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Query shares with filters. In clustered environments, local datastore query is bypassed in favor of clustered registry. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/sharing/smb/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update SMB Share of `id`.
/sharing/smb/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create a SMB Share. `purpose` applies common configuration presets depending on intended purpose. `path` path to export over the SMB protocol. If server is clustered, then this path will be relative to the `cluster_volname`. `timemachine` when set, enables Time Machine backups for this share. `ro` when enabled, prohibits write access to the share. `guestok` when enabled, allows access to this share without a password. `hostsallow` is a list of hostnames / IP addresses which have access to this share. `hostsdeny` is a list of hostnames / IP addresses which are not allowed access to this share. If a handful of hostnames are to be only allowed access, `hostsdeny` can be passed "ALL" which means that it will deny access to ALL hostnames except for the ones which have been listed in `hostsallow`. `acl` enables support for storing the SMB Security Descriptor as a Filesystem ACL. `streams` enables support for storing alternate datastreams as filesystem extended attributes. `fsrvp` enables support for the filesystem remote VSS protocol. This allows clients to create ZFS snapshots through RPC. `shadowcopy` enables support for the volume shadow copy service. `auxsmbconf` is a string of additional smb4.conf parameters not covered by the system's API.
/sharing/smb
| Name | Description |
|---|---|
| body |
Retrieve pre-defined configuration sets for specific use-cases. These parameter combinations are often non-obvious, but beneficial in these scenarios.
/sharing/smb/presets
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/sharing/webdav
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Update Webdav Share of `id`.
/sharing/webdav/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/sharing/webdav/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update Webdav Share of `id`.
/sharing/webdav/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create a Webdav Share. `ro` when enabled prohibits users from writing to this share. `perm` when enabled automatically recursively changes the ownership of this share to webdav ( user and group both ).
/sharing/webdav
| Name | Description |
|---|---|
| body |
/smart
Update SMART Service Configuration. `interval` is an integer value in minutes which defines how often smartd activates to check if any tests are configured to run. `critical`, `informational` and `difference` are integer values on which alerts for SMART are configured if the disks temperature crosses the assigned threshold for each respective attribute. They default to 0 which indicates they are disabled.
/smart
| Name | Description |
|---|---|
| body |
Returns disk choices for S.M.A.R.T. test. `full_disk` will return full disk objects instead of just names.
/smart/test/disk_choices
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/smart/test
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete SMART Test Task of `id`.
/smart/test/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/smart/test/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update SMART Test Task of `id`.
/smart/test/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Run manual SMART tests for `disks`. `type` indicates what type of SMART test will be ran and must be specified.
/smart/test/manual_test
| Name | Description |
|---|---|
| body |
Create a SMART Test Task. `disks` is a list of valid disks which should be monitored in this task. `type` is specified to represent the type of SMART test to be executed. `all_disks` when enabled sets the task to cover all disks in which case `disks` is not required.
/smart/test
| Name | Description |
|---|---|
| body |
Get disk(s) S.M.A.R.T. test(s) results. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/smart/test/results
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
List of valid choices for IP addresses to which to bind the SMB service. Addresses assigned by DHCP are excluded from the results.
/smb/bindip_choices
Return currently connected clients count.
/smb/client_count
List of domains visible to winbindd. Returns empty list if winbindd is stopped.
/smb/domain_choices
/smb
Retrieves an ACL from a remote SMB server. `server` IP Address or hostname of the remote server `share` Share name `path` path on the remote SMB server. Use "" to separate path components `username` username to use for authentication `password` password to use for authentication `use_kerberos` use credentials to get a kerberos ticket for authentication. AD only. `output_format` format for resulting ACL data. Choices are either 'SMB', which will present the information as a Windows SD or 'LOCAL', which formats the ACL information according local filesystem of the TrueNAS server.
/smb/get_remote_acl
| Name | Description |
|---|---|
| body |
Update SMB Service Configuration. `netbiosname` defaults to the original hostname of the system. `netbiosalias` a list of netbios aliases. If Server is joined to an AD domain, additional Kerberos Service Principal Names will be generated for these aliases. `workgroup` specifies the NetBIOS workgroup to which the TrueNAS server belongs. This will be automatically set to the correct value during the process of joining an AD domain. `workgroup` and `netbiosname` should have different values. `enable_smb1` allows legacy SMB clients to connect to the server when enabled. `aapl_extensions` enables support for SMB2 protocol extensions for MacOS clients. This is not a requirement for MacOS support, but is currently a requirement for time machine support. `localmaster` when set, determines if the system participates in a browser election. `guest` attribute is specified to select the account to be used for guest access. It defaults to "nobody". The group specified as the SMB `admin_group` will be automatically added as a foreign group member of S-1-5-32-544 (builtindmins). This will afford the group all privileges granted to a local admin. Any SMB group may be selected (including AD groups). `ntlmv1_auth` enables a legacy and insecure authentication method, which may be required for legacy or poorly-implemented SMB clients. `smb_options` smb.conf parameters that are not covered by the above supported configuration options may be added as an smb_option. Not all options are tested or supported, and behavior of smb_options may change between releases. Stability of smb.conf options is not guaranteed.
/smb
| Name | Description |
|---|---|
| body |
Returns SMB server status (sessions, open files, locks, notifications). `info_level` type of information requests. Defaults to ALL. `status_options` additional options to filter query results. Supported values are as follows: `verbose` gives more verbose status output `fast` causes smbstatus to not check if the status data is valid by checking if the processes that the status data refer to all still exist. This speeds up execution on busy systems and clusters but might display stale data of processes that died without cleaning up properly. `restrict_user` specifies the limits results to the specified user.
/smb/status
| Name | Description |
|---|---|
| body |
/smb/unixcharset_choices
/snmp
Update SNMP Service Configuration. `v3` when set enables SNMP version 3. `v3_username`, `v3_authtype`, `v3_password`, `v3_privproto` and `v3_privpassphrase` are only used when `v3` is enabled.
/snmp
| Name | Description |
|---|---|
| body |
Available choices for the bindiface attribute of SSH service.
/ssh/bindiface_choices
/ssh
Update settings of SSH daemon service. If `bindiface` is empty it will listen for all available addresses.
/ssh
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/staticroute
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete Static Route of `id`.
/staticroute/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/staticroute/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update Static Route of `id`.
/staticroute/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create a Static Route. Address families of `gateway` and `destination` should match when creating a static route. `description` is an optional attribute for any notes regarding the static route.
/staticroute
| Name | Description |
|---|---|
| body |
Get data points from rrd files.
/stats/get_data
| Name | Description |
|---|---|
| body |
Returns info about a given dataset from some source.
/stats/get_dataset_info
| Name | Description |
|---|---|
| body |
Returns an object with all available sources tried with metric datasets.
/stats/get_sources
Returns maximum uploaded file size for `support.attach_ticket`
/support/attach_ticket_max_size
Fetch issue categories using access token `token`. Returns a dict with the category name as a key and id as value.
/support/fetch_categories
| Name | Description |
|---|---|
| body |
Returns list of pairs of field names and field titles for Proactive Support.
/support/fields
/support
Returns whether Proactive Support is available and enabled.
/support/is_available_and_enabled
Returns whether Proactive Support is available for this product type and current license.
/support/is_available
Creates a new ticket for support. This is done using the support proxy API. For TrueNAS SCALE it will be created on JIRA and for TrueNAS SCALE Enterprise on Salesforce. For SCALE `criticality`, `environment`, `phone`, `name` and `email` attributes are not required. For SCALE Enterprise `token` and `type` attributes are not required.
/support/new_ticket
| Name | Description |
|---|---|
| body |
Update Proactive Support settings.
/support
| Name | Description |
|---|---|
| body |
Returns an unique boot identifier. It is supposed to be unique every system boot.
/system/boot_id
Return environment in which product is running. Possible values: - DEFAULT - EC2
/system/environment
Returns whether the `feature` is enabled or not
/system/feature_enabled
| Name | Description |
|---|---|
| body |
Retrieve a hex string that is generated based on the contents of the `/etc/hostid` file. This is a permanent value that persists across reboots/upgrades and can be used as a unique identifier for the machine.
/system/host_id
Returns basic system information.
/system/info
FreeNAS is now TrueNAS CORE. DEPRECATED: Use `system.product_type`
/system/is_freenas
Returns whether software version of the system is stable.
/system/is_stable
Update license file.
/system/license_update
| Name | Description |
|---|---|
| body |
Returns name of the product we are using.
/system/product_name
Returns the type of the product. SCALE - TrueNAS SCALE, community version SCALE_ENTERPRISE - TrueNAS SCALE Enterprise, appliance version
/system/product_type
Returns whether the system completed boot and is ready to use
/system/ready
Reboots the operating system. Emits an "added" event of name "system" and id "reboot".
/system/reboot
| Name | Description |
|---|---|
| body |
Shuts down the operating system. An "added" event of name "system" and id "shutdown" is emitted when shutdown is initiated.
/system/shutdown
| Name | Description |
|---|---|
| body |
Returns system state: "BOOTING" - System is booting "READY" - System completed boot and is ready to use "SHUTTING_DOWN" - System is shutting down
/system/state
Returns software version of the system.
/system/version
/system/advanced
Update System Advanced Service Configuration. `consolemenu` should be disabled if the menu at console is not desired. It will default to standard login in the console if disabled. `autotune` when enabled executes autotune script which attempts to optimize the system based on the installed hardware. When `syslogserver` is defined, logs of `sysloglevel` or above are sent. `consolemsg` is a deprecated attribute and will be removed in further releases. Please, use `consolemsg` attribute in the `system.general` plugin. `isolated_gpu_pci_ids` is a list of PCI ids which are isolated from host system.
/system/advanced
| Name | Description |
|---|---|
| body |
Returns configured global SED password.
/system/advanced/sed_global_password
Get available choices for `serialport`.
/system/advanced/serial_port_choices
Return choices of certificate authorities which can be used for `syslog_tls_certificate_authority`.
/system/advanced/syslog_certificate_authority_choices
Return choices of certificates which can be used for `syslog_tls_certificate`.
/system/advanced/syslog_certificate_choices
Returns country choices.
/system/general/country_choices
/system/general
Returns kbdmap choices.
/system/general/kbdmap_choices
Returns language choices.
/system/general/language_choices
Returns configured local url in the format of protocol://host:port
/system/general/local_url
Update System General Service Configuration. `ui_certificate` is used to enable HTTPS access to the system. If `ui_certificate` is not configured on boot, it is automatically created by the system. `ui_httpsredirect` when set, makes sure that all HTTP requests are converted to HTTPS requests to better enhance security. `ui_address` and `ui_v6address` are a list of valid ipv4/ipv6 addresses respectively which the system will listen on. `syslogserver` and `sysloglevel` are deprecated fields as of 11.3 and will be permanently moved to system.advanced.update for 12.0
/system/general
| Name | Description |
|---|---|
| body |
Returns time zone choices.
/system/general/timezone_choices
Returns UI ipv4 address choices.
/system/general/ui_address_choices
Return choices of certificates which can be used for `ui_certificate`.
/system/general/ui_certificate_choices
Returns available HTTPS protocols.
/system/general/ui_httpsprotocols_choices
Restart HTTP server to use latest UI settings. HTTP server will be restarted after `delay` seconds.
/system/general/ui_restart
| Name | Description |
|---|---|
| body |
Restart HTTP server to use latest UI settings. HTTP server will be restarted after `delay` seconds.
/system/general/ui_restart
| Name | Description |
|---|---|
| body |
Returns UI ipv6 address choices.
/system/general/ui_v6address_choices
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/system/ntpserver
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete NTP server of `id`.
/system/ntpserver/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/system/ntpserver/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update NTP server of `id`.
/system/ntpserver/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Add an NTP Server. `address` specifies the hostname/IP address of the NTP server. `burst` when enabled makes sure that if server is reachable, sends a burst of eight packets instead of one. This is designed to improve timekeeping quality with the server command. `iburst` when enabled speeds up the initial synchronization, taking seconds rather than minutes. `prefer` marks the specified server as preferred. When all other things are equal, this host is chosen for synchronization acquisition with the server command. It is recommended that they be used for servers with time monitoring hardware. `minpoll` is minimum polling time in seconds. It must be a power of 2 and less than `maxpoll`. `maxpoll` is maximum polling time in seconds. It must be a power of 2 and greater than `minpoll`. `force` when enabled forces the addition of NTP server even if it is currently unreachable.
/system/ntpserver
| Name | Description |
|---|---|
| body |
/systemdataset
Retrieve pool choices which can be used for configuring system dataset.
/systemdataset/pool_choices
Update System Dataset Service Configuration. `pool` is the name of a valid pool configured in the system which will be used to host the system dataset. `pool_exclude` can be specified to make sure that we don't place the system dataset on that pool if `pool` is not provided.
/systemdataset
| Name | Description |
|---|---|
| body |
/tftp
Return host choices for TFTP service to use.
/tftp/host_choices
Update TFTP Service Configuration. `newfiles` when set enables network devices to send files to the system. `username` sets the user account which will be used to access `directory`. It should be ensured `username` has access to `directory`.
/tftp
| Name | Description |
|---|---|
| body |
/truecommand
Update Truecommand service settings. `api_key` is a valid API key generated by iX Portal.
/truecommand
| Name | Description |
|---|---|
| body |
Accept TrueNAS EULA.
/truenas/accept_eula
Returns what type of hardware this is, detected from dmidecode.
/truenas/get_chassis_hardware
Returns stored customer information.
/truenas/get_customer_information
Returns the TrueNAS End-User License Agreement (EULA).
/truenas/get_eula
Returns whether the EULA is accepted or not.
/truenas/is_eula_accepted
Returns if system is marked as production.
/truenas/is_production
Sets system production state and optionally sends initial debug.
/truenas/set_production
| Name | Description |
|---|---|
| body |
Updates customer information.
/truenas/update_customer_information
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/tunable
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete Tunable of `id`.
/tunable/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/tunable/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update Tunable of `id`.
/tunable/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create a Tunable. `var` represents name of the sysctl/loader/rc variable. `type` for SCALE should be one of the following: 1) SYSCTL - Configure `var` for sysctl(8)
/tunable
| Name | Description |
|---|---|
| body |
Retrieve tunable type choices supported in the system
/tunable/tunable_type_choices
Checks if there is an update available from update server. status: - REBOOT_REQUIRED: an update has already been applied - AVAILABLE: an update is available - UNAVAILABLE: no update available - HA_UNAVAILABLE: HA is non-functional
/update/check_available
| Name | Description |
|---|---|
| body |
Download updates using selected train.
/update/download
Returns if update auto-download is enabled.
/update/get_auto_download
Gets a list of packages already downloaded and ready to be applied. Each entry of the lists consists of type of operation and name of it, e.g. { "operation": "upgrade", "name": "baseos-11.0 -> baseos-11.1" }
/update/get_pending
| Name | Description |
|---|---|
| body |
Returns available trains dict and the currently configured train as well as the train of currently booted environment.
/update/get_trains
Update the system using a manual update file. `path` must be the absolute path to the update file.
/update/manual
| Name | Description |
|---|---|
| body |
Sets if update auto-download is enabled.
/update/set_auto_download
| Name | Description |
|---|---|
| body |
Set an update train to be used by default in updates.
/update/set_train
| Name | Description |
|---|---|
| body |
Downloads (if not already in cache) and apply an update.
/update/update
| Name | Description |
|---|---|
| body |
Returns choices of UPS drivers supported by the system.
/ups/driver_choices
/ups
/ups/port_choices
Update UPS Service Configuration. `powerdown` when enabled, sets UPS to power off after shutting down the system. `nocommwarntime` is a value in seconds which makes UPS Service wait the specified seconds before alerting that the Service cannot reach configured UPS. `shutdowntimer` is a value in seconds which tells the Service to wait specified seconds for the UPS before initiating a shutdown. This only applies when `shutdown` is set to "BATT". `shutdowncmd` is the command which is executed to initiate a shutdown. It defaults to "poweroff".
/ups
| Name | Description |
|---|---|
| body |
Query users with `query-filters` and `query-options`. As a performance optimization, only local users will be queried by default. Expanded information may be requested by specifying the extra option `"extra": {"additional_information": []}`. The following `additional_information` options are supported: `SMB` - include Windows SID and NT Name for user. If this option is not specified, then these keys will have `null` value. `DS` - include users from Directory Service (LDAP or Active Directory) in results `"extra": {"search_dscache": true}` is a legacy method of querying for directory services users. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/user
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Get the next available/free uid.
/user/get_next_uid
Returns dictionary containing information from struct passwd for the user specified by either the username or uid. Bypasses user cache.
/user/get_user_obj
| Name | Description |
|---|---|
| body |
Return whether the root user has a valid password set. This is used when the system is installed without a password and must be set on first use/login.
/user/has_root_password
Delete user `id`. The `delete_group` option deletes the user primary group if it is not being used by any other user.
/user/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Query users with `query-filters` and `query-options`. As a performance optimization, only local users will be queried by default. Expanded information may be requested by specifying the extra option `"extra": {"additional_information": []}`. The following `additional_information` options are supported: `SMB` - include Windows SID and NT Name for user. If this option is not specified, then these keys will have `null` value. `DS` - include users from Directory Service (LDAP or Active Directory) in results `"extra": {"search_dscache": true}` is a legacy method of querying for directory services users. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/user/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Remove user general purpose `attributes` dictionary `key`.
/user/id/{id}/pop_attribute
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update attributes of an existing user.
/user/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Set user general purpose `attributes` dictionary `key` to `value`. e.g. Setting key="foo" value="var" will result in {"attributes": {"foo": "bar"}}
/user/id/{id}/set_attribute
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Create a new user. If `uid` is not provided it is automatically filled with the next one available. `group` is required if `group_create` is false. `password` is required if `password_disabled` is false. Available choices for `shell` can be retrieved with `user.shell_choices`. `attributes` is a general-purpose object for storing arbitrary user information. `smb` specifies whether the user should be allowed access to SMB shares. User will also automatically be added to the `builtin_users` group.
/user
| Name | Description |
|---|---|
| body |
Return the available shell choices to be used in `user.create` and `user.update`. If `user_id` is provided, shell choices are filtered to ensure the user can access the shell choices provided.
/user/shell_choices
| Name | Description |
|---|---|
| body |
Supported motherboard firmware options.
/vm/bootloader_options
Retrieve CPU Model choices which can be used with a VM guest to emulate the CPU in the guest.
/vm/cpu_model_choices
Returns a dictionary with CPU flags for the hypervisor.
/vm/flags
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/vm
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Get the current maximum amount of available memory to be allocated for VMs. If `overcommit` is true only the current used memory of running VMs will be accounted for. If false all memory (including unused) of runnings VMs will be accounted for. This will include memory shrinking ZFS ARC to the minimum. Memory is of course a very "volatile" resource, values may change abruptly between a second but I deem it good enough to give the user a clue about how much memory is available at the current moment and if a VM should be allowed to be launched.
/vm/get_available_memory
| Name | Description |
|---|---|
| body |
Get the console device from a given guest.
/vm/get_console
| Name | Description |
|---|---|
| body |
Get the display devices from a given guest. If a display device has password configured, `attributes.password_configured` will be set to `true`.
/vm/get_display_devices
| Name | Description |
|---|---|
| body |
/vm/get_memory_usage
| Name | Description |
|---|---|
| body |
The total amount of virtual memory in MB used by guests Returns a dict with the following information: RNP - Running but not provisioned PRD - Provisioned but not running RPRD - Running and provisioned
/vm/get_vmemory_in_use
Retrieve choices for supported guest architecture types and machine choices. Keys in the response would be supported guest architecture(s) on the host and their respective values would be supported machine type(s) for the specific architecture on the host.
/vm/guest_architecture_and_machine_choices
Clone the VM `id`. `name` is an optional parameter for the cloned VM. If not provided it will append the next number available to the VM name.
/vm/id/{id}/clone
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Delete a VM.
/vm/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/vm/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Poweroff a VM.
/vm/id/{id}/poweroff
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update all information of a specific VM. `devices` is a list of virtualized hardware to attach to the virtual machine. If `devices` is not present, no change is made to devices. If either the device list order or data stored by the device changes when the attribute is passed, these actions are taken: 1) If there is no device in the `devices` list which was previously attached to the VM, that device is removed from the virtual machine. 2) Devices are updated in the `devices` list when they contain a valid `id` attribute that corresponds to an existing device. 3) Devices that do not have an `id` attribute are created and attached to `id` VM.
/vm/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Restart a VM.
/vm/id/{id}/restart
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Start a VM. options.overcommit defaults to false, meaning VMs are not allowed to start if there is not enough available memory to hold all configured VMs. If true, VM starts even if there is not enough memory for all configured VMs. Error codes: ENOMEM(12): not enough free memory to run the VM without overcommit
/vm/id/{id}/start
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Get the status of `id` VM. Returns a dict: - state, RUNNING or STOPPED - pid, process id if RUNNING
/vm/id/{id}/status
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Stops a VM. For unresponsive guests who have exceeded the `shutdown_timeout` defined by the user and have become unresponsive, they required to be powered down using `vm.poweroff`. `vm.stop` is only going to send a shutdown signal to the guest and wait the desired `shutdown_timeout` value before tearing down guest vmemory. `force_after_timeout` when supplied, it will initiate poweroff for the VM forcing it to exit if it has not already stopped within the specified `shutdown_timeout`.
/vm/id/{id}/stop
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Returns maximum supported VCPU's
/vm/maximum_supported_vcpus
It returns the next available Display Server Port and Web Port. Returns a dict with two keys `port` and `web`.
/vm/port_wizard
Create a Virtual Machine (VM). `devices` is a list of virtualized hardware to add to the newly created Virtual Machine. Failure to attach a device destroys the VM and any resources allocated by the VM devices. Maximum of 16 guest virtual CPUs are allowed. By default, every virtual CPU is configured as a separate package. Multiple cores can be configured per CPU by specifying `cores` attributes. `vcpus` specifies total number of CPU sockets. `cores` specifies number of cores per socket. `threads` specifies number of threads per core. `ensure_display_device` when set ( the default ) will ensure that the guest always has access to a video device. For headless installations like ubuntu server this is required for the guest to operate properly. However for cases where consumer would like to use GPU passthrough and does not want a display device added should set this to `false`. `arch_type` refers to architecture type and can be specified for the guest. By default the value is `null` and system in this case will choose a reasonable default based on host. `machine_type` refers to machine type of the guest based on the architecture type selected with `arch_type`. By default the value is `null` and system in this case will choose a reasonable default based on `arch_type` configuration. `shutdown_timeout` indicates the time in seconds the system waits for the VM to cleanly shutdown. During system shutdown, if the VM hasn't exited after a hardware shutdown signal has been sent by the system within `shutdown_timeout` seconds, system initiates poweroff for the VM to stop it. `hide_from_msr` is a boolean which when set will hide the KVM hypervisor from standard MSR based discovery and is useful to enable when doing GPU passthrough. SCALE Angelfish: Specifying `devices` is deprecated and will be removed in next major release.
/vm
| Name | Description |
|---|---|
| body |
Create a random mac address. Returns: str: with six groups of two hexadecimal digits
/vm/random_mac
Retrieve supported resolution choices for VM Display devices.
/vm/resolution_choices
Returns "true" if system supports virtualization, "false" otherwise
/vm/supports_virtualization
Retrieve details if virtualization is supported on the system and in case why it's not supported if it isn't.
/vm/virtualization_details
Available choices for Bind attribute.
/vm/device/bind_choices
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/vm/device
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete a VM device of `id`.
/vm/device/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/vm/device/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update a VM device of `id`. Pass `attributes.size` to resize a `dtype` `RAW` device. The raw file will be resized.
/vm/device/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Returns "true" if iommu is enabled, "false" otherwise
/vm/device/iommu_enabled
Available choices for NIC Attach attribute.
/vm/device/nic_attach_choices
Available choices for PCI passthru devices.
/vm/device/passthrough_device_choices
Retrieve details about `device` PCI device.
/vm/device/passthrough_device
| Name | Description |
|---|---|
| body |
Create a new device for the VM of id `vm`. If `dtype` is the `RAW` type and a new raw file is to be created, `attributes.exists` will be passed as false. This means the API handles creating the raw file and raises the appropriate exception if file creation fails. If `dtype` is of `DISK` type and a new Zvol is to be created, `attributes.create_zvol` will be passed as true with valid `attributes.zvol_name` and `attributes.zvol_volsize` values.
/vm/device
| Name | Description |
|---|---|
| body |
Available choices for PCI passthru device.
/vm/device/pptdev_choices
Returns "true" if `dataset` is configured with a VMWare snapshot
/vmware/dataset_has_vms
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/vmware
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Get datastores from VMWare.
/vmware/get_datastores
| Name | Description |
|---|---|
| body |
Returns Virtual Machines on the VMWare host identified by `pk`.
/vmware/get_virtual_machines
| Name | Description |
|---|---|
| body |
Delete VMWare snapshot of `id`.
/vmware/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/vmware/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Update VMWare snapshot of `id`.
/vmware/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Requests datastores from vCenter server and tries to match them with local filesystems. Returns a list of datastores, a list of local filesystems and guessed relationship between them.
/vmware/match_datastores_with_datasets
| Name | Description |
|---|---|
| body |
Create VMWare snapshot. `hostname` is a valid IP address / hostname of a VMWare host. When clustering, this is the vCenter server for the cluster. `username` and `password` are the credentials used to authorize access to the VMWare host. `datastore` is a valid datastore name which exists on the VMWare host.
/vmware
| Name | Description |
|---|---|
| body |
/webdav
Update Webdav Service Configuration. `protocol` specifies which protocol should be used for connecting to Webdav Serivce. Value of "HTTPHTTPS" allows both HTTP and HTTPS connections to the share. `certssl` is a valid id of a certificate configured in the system. This is required if HTTPS connection is desired with Webdave Service. There are 3 types of Authentication supported with Webdav: 1) NONE - No authentication is required 2) BASIC - Password is sent over the network as plaintext 3) DIGEST - Hash of the password is sent over the network `htauth` should be one of the valid types described above.
/webdav
| Name | Description |
|---|---|
| body |
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/webui/image
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Remove the database entry, and then the item if it exists
/webui/image/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
`query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/webui/image/id/{id}
| Name | Description |
|---|---|
| id* |
Integer
Required
|
Clone a given snapshot to a new dataset. Returns: bool: True if succeed otherwise False.
/zfs/snapshot/clone
| Name | Description |
|---|---|
| body |
Query all ZFS Snapshots with `query-filters` and `query-options`. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/zfs/snapshot
| Name | Description |
|---|---|
| limit |
Integer
|
| offset |
Integer
|
| count |
Boolean
|
| sort |
String
|
Delete snapshot of name `id`. `options.defer` will defer the deletion of snapshot.
/zfs/snapshot/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Query all ZFS Snapshots with `query-filters` and `query-options`. `query-options.extra` can be specified as query parameters with prefixing them with `extra.` prefix. For example, `extra.retrieve_properties=false` will pass `retrieve_properties` as an extra argument to pool/dataset endpoint.
/zfs/snapshot/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
/zfs/snapshot/id/{id}
| Name | Description |
|---|---|
| id* |
String
Required
|
Take a snapshot from a given dataset.
/zfs/snapshot
| Name | Description |
|---|---|
| body |
Remove a snapshot from a given dataset. Returns: bool: True if succeed otherwise False.
/zfs/snapshot/remove
| Name | Description |
|---|---|
| body |
Rollback to a given snapshot `id`. `options.recursive` will destroy any snapshots and bookmarks more recent than the one specified. `options.recursive_clones` is just like `recursive` but will also destroy any clones. `options.force` will force unmount of any clones. `options.recursive_rollback` will do a complete recursive rollback of each child snapshots for `id`. If any child does not have specified snapshot, this operation will fail.
/zfs/snapshot/rollback
| Name | Description |
|---|---|
| body |