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:
options:
/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:
dev/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 types are supported:
SSH_KEY_PAIR
Which attributes are:
private_keypublic_key (which can be omitted and thus automatically derived from private key)
At least one attribute is required.SSH_CREDENTIALS
Which attributes are:
hostport (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": [ { "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 byid`.
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 taskdirection specifies whether task will PUSH or PULL snapshotstransport 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 connectionLOCAL replicates to or from localhostsource_datasets is a non-empty list of datasets to replicate snapshots fromtarget_dataset is a dataset to put snapshots into. It must exist on target siderecursive and exclude have the same meaning as for Periodic Snapshot Taskproperties control whether we should send dataset properties along with snapshotsperiodic_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 replicationalso_include_naming_schema is a list of naming schemas for push replicationname_regex will replicate all snapshots which names match specified regular expressionauto allows replication to run automatically on schedule or after bound periodic snapshot taskschedule is a schedule to run replication task. Only auto replication tasks without bound periodic
snapshot tasks can have a schedulerestrict_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.only_matching_schedule will only replicate snapshots that match schedule or
restrict_scheduleallow_from_scratch will destroy all snapshots on target side and replicate everything from scratch if none
of the snapshots on target side matches source snapshotsreadonly controls destination datasets readonly property:SET will set all destination datasets to readonly=on after finishing the replicationREQUIRE will require all existing destination datasets to have readonly=on propertyIGNORE will avoid this kind of behaviorhold_pending_snapshots will prevent source snapshots from being deleted by retention of replication fails
for some reasonretention_policy specifies how to delete old snapshots on target side:SOURCE deletes snapshots that are absent on source sideCUSTOM deletes snapshots that are older than lifetime_value and lifetime_unitNONE does not delete any snapshotscompression compresses SSH stream. Available only for SSH transportspeed_limit limits speed of SSH stream. Available only for SSH transportlarge_block, embed and compressed are various ZFS stream flag documented in man zfs sendretries 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:
/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:
/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 |