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

Create a DNS Authenticator

Create a specific DNS Authenticator containing required authentication details for the said provider to successfully connect with it

Create a DNS Authenticator for Route53

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "acme.dns.authenticator.create",
    "params": [{
        "name": "route53_authenticator",
        "authenticator": "route53",
        "attributes": {
            "access_key_id": "AQX13",
            "secret_access_key": "JKW90"
        }
    }]
}

Delete DNS Authenticator of id

Delete a DNS Authenticator of id

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "acme.dns.authenticator.delete",
    "params": [
        1
    ]
}

Update DNS Authenticator of id

Update a DNS Authenticator of id

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "acme.dns.authenticator.update",
    "params": [
        1,
        {
            "name": "route53_authenticator",
            "attributes": {
                "access_key_id": "AQX13",
                "secret_access_key": "JKW90"
            }
        }
    ]
}

Force an update of the AD machine account password. This can be used to refresh the Kerberos principals in the server's system keytab.

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

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.

Wrapper function for 'directoryservices.get_state'. Returns only the state of the Active Directory service.

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.

Returns list of available LDAP schema choices.

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 ='

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.

List of valid choices for IP addresses to which to bind the AFP service.

Update AFP service settings.

bindip is a list of IPs to bind AFP to. Leave blank (empty list) to bind to all available IPs.

map_acls defines how to map the effective permissions of authenticated users. RIGHTS - Unix-style permissions MODE - ACLs NONE - Do not map

chmod_request defines advanced permission control that deals with ACLs. PRESERVE - Preserve ZFS ACEs for named users and groups or POSIX ACL group mask SIMPLE - Change permission as requested without any extra steps IGNORE - Permission change requests are ignored

Dismiss id alert.

List all types of alerts including active/dismissed currently in the system.

List all types of alerts which the system can issue.

List all alert policies which indicate the frequency of the alerts.

Restore id alert which had been dismissed.

Update default Alert settings.

Create an Alert Service of specified type.

If enabled, it sends alerts to the configured type of Alert Service.

Create an Alert Service of Mail type

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "alertservice.create",
    "params": [{
        "name": "Test Email Alert",
        "enabled": true,
        "type": "Mail",
        "attributes": {
            "email": "dev@ixsystems.com"
        },
        "settings": {
            "VolumeVersion": "HOURLY"
        }
    }]
}

Delete Alert Service of id.

List all types of supported Alert services which can be configured with the system.

Send a test alert using type of Alert Service.

Send a test alert using Alert Service of Mail type.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "alertservice.test",
    "params": [{
        "name": "Test Email Alert",
        "enabled": true,
        "type": "Mail",
        "attributes": {
            "email": "dev@ixsystems.com"
        },
        "settings": {}
    }]
}

Update Alert Service of id.

Creates API Key.

name is a user-readable name for key.

Delete API Key id.

Update API Key id.

Specify reset: true to reset this API Key.

Verify username and password

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.

Authenticate session using username and password. Currently only root user is allowed. otp_token must be specified if two factor authentication is enabled.

Authenticate session using API Key.

Deauthenticates an app and if a token exists, removes that from the session.

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] ] ]

Authenticate using a given token id.

Returns true if two factor authorization is required for authorizing user's login.

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.

Generates a new secret for Two Factor Authentication. Returns boolean true on success.

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.

Returns boolean true if provided token is successfully authenticated.

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.

Detach given dev from boot pool.

Returns disks of the boot pool.

Get Automatic Scrub Interval value in days.

Returns the current state of the boot pool, including all vdevs, properties and datasets.

Replace device label on boot pool with dev.

Scrub on boot pool.

Set Automatic Scrub Interval value in days.

Activates boot environment id.

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.

Delete id boot environment. This removes the clone from the system.

Query all Boot Environments with query-filters and query-options.

Sets attributes boot environment id.

Currently only keep attribute is allowed.

Update id boot environment name with a new provided valid name.

Dictionary of popular ACME Servers with their directory URI endpoints which we display automatically in UI

Returns country choices for creating a certificate/csr.

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.

Create an ACME based certificate

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "certificate.create",
    "params": [{
        "tos": true,
        "csr_id": 1,
        "acme_directory_uri": "https://acme-staging-v02.api.letsencrypt.org/directory",
        "name": "acme_certificate",
        "dns_mapping": {
            "domain1.com": "1"
        },
        "create_type": "CERTIFICATE_CREATE_ACME"
    }]
}

Create an Imported Certificate Signing Request

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "certificate.create",
    "params": [{
        "name": "csr",
        "CSR": "CSR string",
        "privatekey": "Private key string",
        "create_type": "CERTIFICATE_CREATE_IMPORTED_CSR"
    }]
}

Create an Internal Certificate

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "certificate.create",
    "params": [{
        "name": "internal_cert",
        "key_length": 2048,
        "lifetime": 3600,
        "city": "Nashville",
        "common": "domain1.com",
        "country": "US",
        "email": "dev@ixsystems.com",
        "organization": "iXsystems",
        "state": "Tennessee",
        "digest_algorithm": "SHA256",
        "signedby": 4,
        "create_type": "CERTIFICATE_CREATE_INTERNAL"
    }]
}

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

Delete certificate of id

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "certificate.delete",
    "params": [
        1,
        true
    ]
}

Dictionary of supported EC curves.

Dictionary of choices for ExtendedKeyUsage extension which can be passed over to usages attribute.

Dictionary of supported key types for certificates.

Returns a dictionary of predefined options for specific use cases i.e openvpn client/server configurations which can be used for creating certificates.

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.

Update a certificate of id

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "certificate.update",
    "params": [
        1,
        {
            "name": "updated_name"
        }
    ]
}

Sign CSR by Certificate Authority of ca_id

Sign CSR's and generate a certificate from it. ca_id provides which CA is to be used for signing a CSR of csr_cert_id which exists in the system

cert_extensions can be specified if specific extensions are to be set in the newly signed certificate.

Sign CSR of csr_cert_id by Certificate Authority of ca_id

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "certificateauthority.ca_sign_csr",
    "params": [{
        "ca_id": 1,
        "csr_cert_id": 1,
        "name": "signed_cert"
    }]
}

Create a new Certificate Authority

Certificate Authorities are classified under following types with the necessary keywords to be passed for create_type attribute to create the respective type of certificate authority

1) Internal Certificate Authority - CA_CREATE_INTERNAL

2) Imported Certificate Authority - CA_CREATE_IMPORTED

3) Intermediate Certificate Authority - CA_CREATE_INTERMEDIATE

Created certificate authorities use RSA keys by default. If an Elliptic Curve Key is desired, then it can be specified with the key_type attribute. If the ec_curve attribute is not specified for the Elliptic Curve Key, default to using "BrainpoolP384R1" curve.

A type is selected by the Certificate Authority Service based on create_type. The rest of the values are validated accordingly and finally a certificate is made based on the selected type.

cert_extensions can be specified to set X509v3 extensions.

Create an Internal Certificate Authority

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "certificateauthority.create",
    "params": [{
        "name": "internal_ca",
        "key_length": 2048,
        "lifetime": 3600,
        "city": "Nashville",
        "common": "domain1.com",
        "country": "US",
        "email": "dev@ixsystems.com",
        "organization": "iXsystems",
        "state": "Tennessee",
        "digest_algorithm": "SHA256"
        "create_type": "CA_CREATE_INTERNAL"
    }]
}

Create an Imported Certificate Authority

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "certificateauthority.create",
    "params": [{
        "name": "imported_ca",
        "certificate": "Certificate string",
        "privatekey": "Private key string",
        "create_type": "CA_CREATE_IMPORTED"
    }]
}

Delete a Certificate Authority of id

Delete a Certificate Authority of id

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "certificateauthority.delete",
    "params": [
        1
    ]
}

Returns a dictionary of predefined options for specific use cases i.e OpenVPN certificate authority configurations which can be used for creating certificate authorities.

Update Certificate Authority of id

Only name and revoked attribute can be updated.

If revoked is enabled, the CA and its complete chain is marked as revoked and added to the CA's certificate revocation list.

Update a Certificate Authority of id

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "certificateauthority.update",
    "params": [
        1,
        {
            "name": "updated_ca_name"
        }
    ]
}

Aborts cloud sync task.

Creates a new cloud_sync entry.

Create a new cloud_sync using amazon s3 attributes, which is supposed to run every hour.

{
  "id": "6841f242-840a-11e6-a437-00e04d680384",
  "msg": "method",
  "method": "cloudsync.create",
  "params": [{
    "description": "s3 sync",
    "path": "/mnt/tank",
    "credentials": 1,
    "minute": "00",
    "hour": "*",
    "daymonth": "*",
    "month": "*",
    "attributes": {
      "bucket": "mybucket",
      "folder": ""
    },
    "enabled": true
  }]
}

Deletes cloud_sync entry id.

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.

Lists all available drives and their types for given Microsoft OneDrive credentials.

{
  "id": "6841f242-840a-11e6-a437-00e04d680384",
  "msg": "method",
  "method": "cloudsync.onedrive_list_drives",
  "params": [{
    "client_id": "...",
    "client_secret": "",
    "token": "{...}",
  }]
}

Returns

[{"drive_type": "PERSONAL", "drive_id": "6bb903a25ad65e46"}]

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": [] } ]

Query all Cloud Sync Tasks with query-filters and query-options.

Create the opposite of cloud sync task id (PULL if it was PUSH and vice versa).

Run the cloud_sync job id, syncing the local data to remote.

Run cloud sync task without creating it.

Updates the cloud_sync entry id with data.

Create Cloud Sync Credentials.

attributes is a dictionary of valid values which will be used to authorize with the provider.

Delete Cloud Sync Credentials of id.

Update Cloud Sync Credentials of id.

Verify if attributes provided for provider are authorized by the provider.

Reset database to configuration defaults.

If reboot is true this job will reboot the system after its completed with a delay of 10 seconds.

Create a bundle of security-sensitive information. These options select which information is included in the bundle:

secretseed: include password secret seed.

pool_keys: include GELI encryption keys.

root_authorized_keys: include "authorized_keys" file for the root user.

If none of these options are set, the bundle is not generated and the database file is provided.

Accepts a configuration file via job pipe.

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

Setup middlewared for remote debugging.

engines: - PTVS: Python Visual Studio - PYDEV: Python Dev (Eclipse/PyCharm) - REMOTE_PDB: Remote vanilla PDB (over TCP sockets)

options: - secret: password for PTVS - host: required for PYDEV, hostname of local computer (developer workstation) - local_path: required for PYDEV, path for middlewared source in local computer (e.g. /home/user/freenas/src/middlewared/middlewared - threaded: run debugger in a new thread instead of event loop

Core helper to call a job marked for download.

Returns the job id and the URL for download.

Returns metadata for every possible event emitted from websocket server.

Get the long running jobs.

Return methods metadata of every available service.

service parameter is optional and filters the result for a single service.

Returns a list of all registered services.

Utility method which just returns "pong". Can be used to keep connection/authtoken alive instead of using "ping" protocol message.

Method that will send an ICMP echo request to "hostname" and will wait up to "timeout" for a reply.

Resize terminal session (/websocket/shell) to cols x rows

Get currently open websocket sessions.

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.

Create a cron job which executes touch /tmp/testfile after every 5 minutes.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "cronjob.create",
    "params": [{
        "enabled": true,
        "schedule": {
            "minute": "5",
            "hour": "*",
            "dom": "*",
            "month": "*",
            "dow": "*"
        },
        "command": "touch /tmp/testfile",
        "description": "Test command",
        "user": "root",
        "stderr": true,
        "stdout": true
    }]
}

Delete cronjob of id.

Job to run cronjob task of id.

Update cronjob of id.

Get info for SERIAL/DISK device types.

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.

Decrypt devices using uploaded encryption key

Get all geli providers

It might be an entire disk or a partition of type freebsd-zfs.

Before a geli encrypted pool can be imported, disks used in the pool should be decrypted and then pool import can proceed as desired. In that case unused can be passed as true, to find out which disks are geli encrypted but not being used by active ZFS pools.

Helper method to get all disks that are not in use, either by the boot pool or the user pools.

Sets overprovision of disk devname to size gigabytes

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)

Returns S.M.A.R.T. attributes values for specified disk name.

Spin down disk by device name

Spin down ada0

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "disk.spindown",
    "params": ["ada0"]
}

Returns temperature for device name using specified S.M.A.R.T. powermode.

Returns temperatures for a list of devices (runs in parallel). See disk.temperature documentation for more details.

Removes overprovisioning of disk devname

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.

Performs a wipe of a disk dev. It can be of the following modes: - QUICK: clean the first few and last megabytes of every partition and disk - FULL: write whole disk with zero's - FULL_RANDOM: write whole disk with random bytes

Query Name Servers with query-filters and query-options.

List supported Dynamic DNS Service Providers.

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.

Call a method in the other node.

Returns a list of reasons why failover is not enabled/functional.

NO_VOLUME - There are no pools configured. NO_VIP - There are no interfaces configured with Virtual IP. NO_SYSTEM_READY - Other storage controller has not finished booting. NO_PONG - Other storage controller is not communicable. NO_FAILOVER - Failover is administratively disabled. NO_LICENSE - Other storage controller has no license. DISAGREE_CARP - Nodes CARP states do not agree. MISMATCH_DISKS - The storage controllers do not have the same quantity of disks. NO_CRITICAL_INTERFACES - No network interfaces are marked critical for failover.

Force this controller to become MASTER.

Get a list of IPs which can be accessed for management via UI.

Returns the hardware type for an HA system. ECHOSTREAM ECHOWARP PUMA SBB ULTIMATE BHYVE MANUAL

Returns True if there is an ongoing failover event.

Checks whether this instance is licensed as a HA unit.

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

Get the current HA status.

Returns: MASTER BACKUP ELECTING IMPORTING ERROR SINGLE

Sync database and files from the other controller.

Sync database and files to the other controller.

reboot as true will reboot the other controller after syncing.

Unlock pools in HA, syncing passphrase between controllers and forcing this controller to be MASTER importing the pools.

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.

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.

Perform the last stage of an HA upgrade.

This will activate the new boot environment on the Standby Controller and reboot it.

Verify if HA upgrade is pending.

upgrade_finish needs to be called to finish the HA upgrade process if this method returns true.

Returns True if the ACL can be fully expressed as a file mode without losing any access rules, or if the path does not support NFSv4 ACLs (for example a path on a tmpfs filesystem).

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.

Get list of default ACL types.

Job to get contents of path.

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.

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.

Errata about ACLType NFSv4:

simplified returns a shortened form of the ACL permset and flags.

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. Equivalent to modify_set.

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.

In all cases we replace 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. We also remove it here to avoid confusion.

Get the contents of a directory.

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

Job to put contents to path.

Set ACL of a given path. Takes the following parameters: path full path to directory or file.

dacl "simplified" ACL here or a full ACL.

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)

In all cases we replace 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.

Remove extended ACL from specified path.

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.

Return the filesystem stat(2) for a given path.

Return stats from the filesystem of a given path.

Raises: CallError(ENOENT) - Path not found

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 client idle time in seconds before client is disconnected.

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.

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.

Delete group id.

The delete_users option deletes all users that have this group as their primary group.

Returns dictionary containing information from struct grp for the group specified by either the groupname or gid. Bypasses group cache.

Get the next available/free gid.

Query groups with query-filters and query-options. As a performance optimization, only local groups will be queried by default.

Groups from directory services such as NIS, LDAP, or Active Directory will be included in query results if the option {'extra': {'search_dscache': True}} is specified.

Update attributes of an existing group.

Returns array of valid idmap backend choices per directory service.

This returns full information about idmap backend options. Not all options are valid for every backend.

Stop samba, remove the winbindd_cache.tdb file, start samba, flush samba's cache. This should be performed after finalizing idmap changes.

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.

Delete a domain by id. Deletion of default system domains is not permitted.

Returns a list of supported keys for the specified idmap backend.

Update a domain by id.

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.

Delete init/shutdown task of id.

Update initshutdown script task of id.

Return available interface choices for bridge_members attribute.

id is the name of the bridge interface to update or null for a new bridge interface.

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.

Returns wether 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.

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.

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.

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.

Delete Interface of id.

Returns whether there are pending interfaces changes to be applied or not.

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" }, ]

Return available interface choices for lag_ports attribute.

id is the name of the LAG interface to update or null for a new LAG interface.

Query Interfaces with query-filters and query-options

Rollback pending interfaces changes.

Update Interface of id.

Return available interface choices for vlan_parent_interface attribute.

Returns the interface this websocket is connected to.

Returns the ip this websocket is connected to.

Return a list with the IPMI channels available.

Turn on IPMI chassis identify light.

To turn off specify 0 as seconds.

Returns a boolean true value indicating if ipmi device is loaded.

Query all IPMI Channels with query-filters and query-options.

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.

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.

Delete iSCSI Authorized Access of id.

Update iSCSI Authorized Access of id.

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 and it should be ensured that it does not come under a jail root.

With type being set to DISK, a valid ZVOL or DISK should be provided.

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.

Delete iSCSI Extent of id.

If id iSCSI Extent's type was configured to FILE, remove can be set to remove the configured file.

Exclude will exclude the path from being in the used_zvols list, allowing the user to keep the same item on update

Update iSCSI Extent of id.

Returns whether iSCSI ALUA is enabled or not.

Get a list of currently running iSCSI sessions. This includes initiator and target names and the unique connection IDs.

alua is a no-op for FreeNAS.

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.

Delete iSCSI initiator of id.

Update iSCSI initiator of id.

Create a new iSCSI Portal.

discovery_authgroup is required for CHAP and CHAP_MUTUAL.

Delete iSCSI Portal id.

Returns possible choices for listen.ip attribute of portal create and update.

Update iSCSI Portal id.

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.

Delete iSCSI Target of id.

Deleting an iSCSI Target makes sure we delete all Associated Targets which use id iSCSI Target.

Update iSCSI Target of id.

Create an Associated Target.

lunid will be automatically assigned if it is not provided based on the target.

Delete Associated Target of id.

Update Associated Target of id.

Activates a pool for iocage usage, and deactivates the rest.

Cleans all iocage datasets of ds_type

Creates a jail.

Retrieve default configuration for iocage jails.

Takes a jail and destroys it.

Issues a command inside a jail.

Export jail to compressed file.

Fetches a release or plugin.

Manipulate a jails fstab

Returns the activated pool if there is one, or None

Import jail from compressed file.

compression algorithm: None indicates that middlewared is to automatically determine which compression algorithm to use based on the compressed file extension. If multiple copies are found, an exception is raised.

path is the directory where the exported jail lives. It defaults to the iocage images dataset.

Returns a dictionary of interface choices which can be used with creating/updating jails.

Query all jails with query-filters and query-options.

Does specified action on rc enabled (boot=on) jails

List installed or available releases which can be downloaded.

Takes a jail and restarts it.

Takes a jail and starts it.

Takes a jail and stops it.

Sets a jail property.

Update default properties for iocage which will remain true for all jails moving on i.e nat_backend

Updates specified jail to latest patch level.

Returns a dictionary of interface choices which can be used with vnet_default_interface property.

appdefaults_aux add parameters to "appdefaults" section of the krb5.conf file.

libdefaults_aux add parameters to "libdefaults" section of the krb5.conf file.

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

Delete kerberos keytab by id, and force regeneration of system keytab.

Returns content of system keytab (/etc/krb5.keytab).

Update kerberos keytab by id.

Upload a keytab file. This method expects the keytab file to be uploaded using the /_upload/ endpoint.

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.

Delete a kerberos realm by ID.

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.

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_key * public_key (which can be omitted and thus automatically derived from private key) At least one attribute is required.

• SSH_CREDENTIALS Which attributes are:
• host
• port (default 22)
• username (default root)
• private_key (Keychain Credential ID)
• remote_host_key (you can use keychaincredential.remote_ssh_host_key_scan do discover it)
• cipher: one of STANDARD, FAST, or DISABLED (last requires special support from both SSH server and client)
• connect_timeout (default 10)

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "keychaincredential.create",
    "params": [{
        "name": "Work SSH connection",
        "type": "SSH_CREDENTIALS",
        "attributes": {
            "host": "work.freenas.org",
            "private_key": 12,
            "remote_host_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMn1VjdSMatGnxbOsrneKyai+dh6d4Hm"
        }
    }]
}

Delete Keychain Credential with specific id

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "keychaincredential.delete",
    "params": [
        13
    ]
}

Generate a public/private key pair

Generate a public/private key pair (useful for SSH_KEY_PAIR type)

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "keychaincredential.generate_ssh_key_pair",
    "params": []
}

Discover a remote host key

Discover a remote host key (useful for SSH_CREDENTIALS)

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "keychaincredential.delete",
    "params": [{
        "host": "work.freenas.org"
    }]
}

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.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "keychaincredential.keychain_remote_ssh_semiautomatic_setup",
    "params": [{
        "name": "Work SSH connection",
        "url": "https://work.freenas.org",
        "token": "8c8d5fd1-f749-4429-b379-9c186db4f834",
        "private_key": 12
    }]
}

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

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "keychaincredential.update",
    "params": [
        13,
        {
            "name": "Work SSH connection",
            "attributes": {
                "host": "work.ixsystems.com",
                "private_key": 12,
                "remote_host_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMn1VjdSMatGnxbOsrneKyai+dh6d4Hm"
            }
        }
    ]
}

Returns list of objects that use this credential.

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.

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.

Sync ZFS/SED keys between KMIP Server and TN database.

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.

Wrapper function for 'directoryservices.get_state'. Returns only the state of the LDAP service.

Returns list of available LDAP schema choices.

Returns list of SSL choices.

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.

Returns country choices for 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.

Sends mail using configured mail settings.

text will be formatted to HTML using Markdown and rendered using default E-Mail template. You can put your own HTML using html. If html is null, no HTML MIME part will be added to E-Mail.

If attachments is true, a list compromised of the following dict is required via HTTP upload: - headers(list) - name(str) - value(str) - params(dict) - content (str)

[ { "headers": [ { "name": "Content-Transfer-Encoding", "value": "base64" }, { "name": "Content-Type", "value": "application/octet-stream", "params": { "name": "test.txt" } } ], "content": "dGVzdAo=" } ]

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.

Get multipaths and their consumers.

Get all multipaths

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "multipath.query",
    "params": []
}

returns

:::javascript
[
  {
    "type": "root",
    "name": "multipath/disk5",
    "status": "OPTIMAL",
    "children": [
      {
        "type": "consumer",
        "name": "da1",
        "status": "PASSIVE",
        "lun_id": "5000cca05c9e1400"
      },
      {
        "type": "consumer",
        "name": "da23",
        "status": "ACTIVE",
        "lun_id": "5000cca05c9e1400"
      }
    ]
  }
]

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.

Retrieve general information for current Network.

Returns a dictionary. For example:

{
    "ips": {
        "vtnet0": {
            "IPV4": [
                "192.168.0.15/24"
            ]
        }
    },
    "default_routes": [
        "192.168.0.1"
    ],
    "nameservers": [
        "192.168.0.1"
    ]
}

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.

Returns ip choices for NFS service to use

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.

Update NFS Service Configuration to listen on 192.168.0.10 and use NFSv4

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.resilver.update",
    "params": [{
        "bindip": [
            "192.168.0.10"
        ],
        "v4": true
    }]
}

Wrapper function for 'directoryservices.get_state'. Returns only the state of the NIS service.

Update NIS Service Configuration.

domain is the name of NIS domain.

servers is a list of hostnames/IP addresses.

secure_mode when enabled sets ypbind(8) to refuse binding to any NIS server not running as root on a TCP port over 1024.

manycast when enabled sets ypbind(8) to bind to the server that responds the fastest.

enable enables and starts the NIS service. The NIS service is disabled when this value is changed to False.

Returns a dictionary of valid authentication algorithms which can be used with OpenVPN server.

Returns a dictionary of valid ciphers which can be used with OpenVPN server.

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.

Returns a dictionary of valid authentication algorithms which can be used with OpenVPN server.

Returns a dictionary of valid ciphers which can be used with OpenVPN server.

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.

Reset OpenVPN server's TLS static key which will be used to encrypt/authenticate control channel packets.

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.

List available plugins which can be fetched for plugin_repository.

Create a Plugin.

plugin_name is the name of the plugin specified by the INDEX file in "plugin_repository" and it's JSON file.

jail_name is the name of the jail that will manage the plugin. Required.

props is a list of jail properties that the user manually sets. Plugins should always set the jail networking capability with DHCP, IP Address, or NAT properties. i.e dhcp=1 / ip4_addr="192.168.0.2" / nat=1

plugin_repository is a git URI that fetches data for plugin_name.

branch is the FreeNAS repository branch to use as the base for the plugin_repository. The default is to use the current system version. Example: 11.3-RELEASE.

Retrieve default properties specified for plugin in the plugin's manifest.

When refresh is specified, plugin_repository is updated before retrieving plugin's default properties.

Delete plugin id.

List officially supported plugin repositories.

Query installed plugins with query-filters and query-options.

Update plugin id.

Updates specified plugin to latest available plugin version and optionally update plugin to latest patch level.

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.

Return a list of services dependent of this pool.

Responsible for telling the user whether there is a related share, asking for confirmation.

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"]
}

Create a pool named "tank", raidz1 with 3 disks, 1 cache disk, 1 ZIL/log disk and 1 hot spare disk.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.create",
    "params": [{
        "name": "tank",
        "topology": {
            "data": [
                {"type": "RAIDZ1", "disks": ["da1", "da2", "da3"]}
            ],
            "cache": [
                {"type": "STRIPE", "disks": ["da4"]}
            ],
            "log": [
                {"type": "RAIDZ1", "disks": ["da5"]}
            ],
            "spares": ["da6"]
        }
    }]
}

Detach a disk from pool of id id.

label is the vdev guid or device name.

Detach ZFS device.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.detach,
    "params": [1, {
        "label": "80802394992848654"
    }]
}

Download encryption key for a given pool id.

Expand pool to fit all available disk space.

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.

Export pool of id 1.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.export,
    "params": [1, {
        "cascade": true,
        "destroy": false
    }]
}

Returns all available datasets, except system datasets.

Get all datasets.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.filesystem_choices",
    "params": []
}

Get only filesystems (exclude volumes).

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.filesystem_choices",
    "params": [["FILESYSTEM"]]
}

Get all disks in use by pools. If id is provided only the disks from the given pool id will be returned.

Import a disk, by copying its content to a pool.

Import a FAT32 (msdosfs) disk.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.import_disk,
    "params": [
        "/dev/da0", "msdosfs", {}, "/mnt/tank/mydisk"
    ]
}

Autodetect filesystem type for pool.import_disk.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.import_disk_autodetect_fs_type",
    "params": ["/dev/da0"]
}

Get a list of locales for msdosfs type to be used in pool.import_disk.

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.

Import a pool found with pool.import_find.

If a name is specified the pool will be imported using that new name.

passphrase is required while importing an encrypted pool. In that case this method needs to be called using /_upload/ endpoint with the encryption key.

If enable_attachments is set to true, attachments that were disabled during pool export will be re-enabled.

Errors: ENOENT - Pool not found

Import pool of guid 5571830764813710860.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.import_pool,
    "params": [{
        "guid": "5571830764813710860"
    }]
}

Returns whether or not the pool of id is on the latest version and with all feature flags enabled.

Check if pool of id 1 is upgraded.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.is_upgraded",
    "params": [1]
}

Lock encrypted pool id.

Offline a disk from pool of id id.

label is the vdev guid or device name.

Offline ZFS device.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.offline,
    "params": [1, {
        "label": "80802394992848654"
    }]
}

Online a disk from pool of id id.

label is the vdev guid or device name.

Online ZFS device.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.online,
    "params": [1, {
        "label": "80802394992848654"
    }]
}

Create/Change/Remove passphrase for an encrypted pool.

Setting passphrase to null will remove the passphrase. admin_password is required when changing or removing passphrase.

Change passphrase for pool 1.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.passphrase,
    "params": [1, {
        "passphrase": "mysecretpassphrase",
        "admin_password": "rootpassword"
    }]
}

Returns a list of running processes using this pool.

Add Recovery key for encrypted pool id.

This is to be used with core.download which will provide an URL to download the recovery key.

Remove recovery key for encrypted pool id.

Remove recovery key for pool 1.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.recoverykey_rm,
    "params": [1, {
        "admin_password": "rootpassword"
    }]
}

Rekey encrypted pool id.

Rekey pool 1.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.rekey,
    "params": [1, {
        "admin_password": "rootpassword"
    }]
}

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

Remove ZFS device.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.remove,
    "params": [1, {
        "label": "80802394992848654"
    }]
}

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

Replace missing ZFS device with disk {serial}FOO.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.replace",
    "params": [1, {
        "label": "80802394992848654",
        "disk": "{serial}FOO"
    }]
}

Performs a scrub action to pool of id.

action can be either of "START", "STOP" or "PAUSE".

Start scrub on pool of id 1.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.scrub",
    "params": [1, "START"]
}

Unlock encrypted pool id.

passphrase is required of a recovery key is not provided.

If recoverykey is true this method expects the recovery key file to be uploaded using the /_upload/ endpoint.

services_restart is a list of services to be restarted when the pool gets unlocked. Said list be be retrieve using pool.unlock_services_restart_choices.

Unlock pool of id 1, restarting "cifs" service.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.unlock,
    "params": [1, {
        "passphrase": "mysecretpassphrase",
        "services_restart": ["cifs"]
    }]
}

Get a mapping of services identifiers and labels that can be restart on volume unlock.

Update pool of id, adding the new topology.

The type of data must be the same of existing vdevs.

Add a new set of raidz1 to pool of id 1.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.update",
    "params": [1, {
        "topology": {
            "data": [
                {"type": "RAIDZ1", "disks": ["da7", "da8", "da9"]}
            ]
        }
    }]
}

Upgrade pool of id to latest version with all feature flags.

Upgrade pool of id 1.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.upgrade",
    "params": [1]
}

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"] } ]

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

Retrieve compression algorithm supported by ZFS.

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.

Create a dataset within tank pool.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.dataset.create,
    "params": [{
        "name": "tank/myuser",
        "comments": "Dataset for myuser"
    }]
}

Delete dataset/zvol id.

recursive will also delete/destroy all children datasets. force will force delete busy datasets.

Delete "tank/myuser" dataset.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.dataset.delete",
    "params": ["tank/myuser"]
}

Retrieve encryption algorithms supported for ZFS dataset encryption.

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.

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 } ]

Export own encryption key for dataset id. If download is true, key will be downloaded as a text file, otherwise it will be returned as string.

Please refer to websocket documentation for downloading the file.

Export keys for id and its children which are stored in the system. The exported file is a JSON file which has a dictionary containing dataset names as keys and their keys as the value.

Please refer to websocket documentation for downloading the file.

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.

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.

Locks id dataset. It will unmount the dataset and its children before locking.

Set permissions for a dataset id. Permissions may be specified as either a posix mode or an nfsv4 acl. Setting mode will fail if the dataset has an existing nfsv4 acl. In this case, the option stripacl must be set to True.

Change permissions of dataset "tank/myuser" to myuser:wheel and 755.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.dataset.permission",
    "params": ["tank/myuser", {
        "user": "myuser",
        "acl": [],
        "group": "wheel",
        "mode": "755",
        "options": {"recursive": true, "stripacl": true},
    }]
}

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" } ]

Promote the cloned dataset id.

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).

Helper method to get recommended size for a new zvol (dataset of type VOLUME).

Get blocksize for pool "tank".

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.dataset.recommended_zvol_blocksize",
    "params": ["tank"]
}

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.

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.

Updates a dataset/zvol id.

Update the comments for "tank/myuser".

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.dataset.update,
    "params": ["tank/myuser", {
        "comments": "Dataset for myuser, UPDATE #1"
    }]
}

Create a user property for a given id dataset.

Delete user property dataset_user_prop_delete.name for id dataset.

Query all user properties for ZFS datasets.

Update dataset_user_prop_update.name user property for id dataset.

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).

Enable pool resilver priority all business days from 7PM to 5AM.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.resilver.update",
    "params": [{
        "enabled": true,
        "begin": "19:00",
        "end": "05:00",
        "weekday": [1, 2, 3, 4, 5]
    }]
}

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.

Create a scrub task for pool of id 1, to run every sunday but with a threshold of 35 days. The check will run at 3AM every sunday.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.scrub.create"
    "params": [{
        "pool": 1,
        "threshold": 35,
        "description": "Monthly scrub for tank",
        "schedule": "0 3 * * 7",
        "enabled": true
    }]
}

Delete scrub task of id.

Initiate a scrub of a pool name if last scrub was performed more than threshold days before.

Update scrub task of id.

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.

Create a recursive Periodic Snapshot Task for dataset data/work excluding data/work/temp. Snapshots will be created on weekdays every hour from 09:00 to 18:00 and will be stored for two weeks.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.snapshottask.create",
    "params": [{
        "dataset": "data/work",
        "recursive": true,
        "exclude": ["data/work/temp"],
        "lifetime_value": 2,
        "lifetime_unit": "WEEK",
        "naming_schema": "auto_%Y-%m-%d_%H-%M",
        "schedule": {
            "minute": "0",
            "hour": "*",
            "dom": "*",
            "month": "*",
            "dow": "1,2,3,4,5",
            "begin": "09:00",
            "end": "18:00"
        }
    }]
}

Delete a Periodic Snapshot Task with specific id

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.snapshottask.delete",
    "params": [
        1
    ]
}

Execute a Periodic Snapshot Task of id.

Update a Periodic Snapshot Task with specific id

See the documentation for create method for information on payload contents

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "pool.snapshottask.update",
    "params": [
        1,
        {
            "dataset": "data/work",
            "recursive": true,
            "exclude": ["data/work/temp"],
            "lifetime_value": 2,
            "lifetime_unit": "WEEK",
            "naming_schema": "auto_%Y-%m-%d_%H-%M",
            "schedule": {
                "minute": "0",
                "hour": "*",
                "dom": "*",
                "month": "*",
                "dow": "1,2,3,4,5",
                "begin": "09:00",
                "end": "18:00"
            }
        }
    ]
}

Count how many existing snapshots of dataset match naming_schema.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "replication.count_eligible_manual_snapshots",
    "params": [
        "repl/work",
        ["auto-%Y-%m-%d_%H-%M"],
        "SSH",
        4
    ]
}

Create a Replication Task

Create a Replication Task that will push or pull ZFS snapshots to or from remote host..

• name specifies a name for replication task
• direction specifies whether task will PUSH or PULL snapshots
• transport is a method of snapshots transfer:
• SSH transfers snapshots via SSH connection. This method is supported everywhere but does not achieve great performance ssh_credentials is a required field for this transport (Keychain Credential ID of type SSH_CREDENTIALS)
• SSH+NETCAT uses unencrypted connection for data transfer. This can only be used in trusted networks and requires a port (specified by range from netcat_active_side_port_min to netcat_active_side_port_max) to be open on netcat_active_side ssh_credentials is also required for control connection
• LOCAL replicates to or from localhost
• source_datasets is a non-empty list of datasets to replicate snapshots from
• target_dataset is a dataset to put snapshots into. It must exist on target side
• recursive and exclude have the same meaning as for Periodic Snapshot Task
• properties control whether we should send dataset properties along with snapshots
• periodic_snapshot_tasks is a list of periodic snapshot task IDs that are sources of snapshots for this replication task. Only push replication tasks can be bound to periodic snapshot tasks.
• naming_schema is a list of naming schemas for pull replication
• also_include_naming_schema is a list of naming schemas for push replication
• auto allows replication to run automatically on schedule or after bound periodic snapshot task
• schedule is a schedule to run replication task. Only auto replication tasks without bound periodic snapshot tasks can have a schedule
• restrict_schedule restricts when replication task with bound periodic snapshot tasks runs. For example, you can have periodic snapshot tasks that run every 15 minutes, but only run replication task every hour.
• Enabling only_matching_schedule will only replicate snapshots that match schedule or restrict_schedule
• allow_from_scratch will destroy all snapshots on target side and replicate everything from scratch if none of the snapshots on target side matches source snapshots
• readonly controls destination datasets readonly property:
• SET will set all destination datasets to readonly=on after finishing the replication
• REQUIRE will require all existing destination datasets to have readonly=on property
• IGNORE will avoid this kind of behavior
• hold_pending_snapshots will prevent source snapshots from being deleted by retention of replication fails for some reason
• retention_policy specifies how to delete old snapshots on target side:
• SOURCE deletes snapshots that are absent on source side
• CUSTOM deletes snapshots that are older than lifetime_value and lifetime_unit
• NONE does not delete any snapshots
• compression compresses SSH stream. Available only for SSH transport
• speed_limit limits speed of SSH stream. Available only for SSH transport
• large_block, embed and compressed are various ZFS stream flag documented in man zfs send
• retries specifies number of retries before considering replication failed

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "replication.create",
    "params": [{
        "name": "Work Backup",
        "direction": "PUSH",
        "transport": "SSH",
        "ssh_credentials": [12],
        "source_datasets", ["data/work"],
        "target_dataset": "repl/work",
        "recursive": true,
        "periodic_snapshot_tasks": [5],
        "auto": true,
        "restrict_schedule": {
            "minute": "0",
            "hour": "*/2",
            "dom": "*",
            "month": "*",
            "dow": "1,2,3,4,5",
            "begin": "09:00",
            "end": "18:00"
        },
        "only_matching_schedule": true,
        "retention_policy": "CUSTOM",
        "lifetime_value": 1,
        "lifetime_unit": "WEEK",
    }]
}

Creates dataset on remote side

Accepts dataset name, transport and SSH credentials ID (for non-local transport)

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "replication.create_dataset",
    "params": [
        "repl/work",
        "SSH",
        7
    ]
}

Delete a Replication Task with specific id

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "replication.delete",
    "params": [
        1
    ]
}

List datasets on remote side

Accepts transport and SSH credentials ID (for non-local transport)

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "replication.list_datasets",
    "params": [
        "SSH",
        7
    ]
}

List all naming schemas used in periodic snapshot and replication tasks.

Create the opposite of replication task id (PULL if it was PUSH and vice versa).

Run Replication Task of id.

Check if target has any snapshots that do not exist on source.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "replication.target_unmatched_snapshots",
    "params": [
        "PUSH",
        ["repl/work", "repl/games"],
        "backup",
        "SSH",
        4
    ]
}

Returns

{
    "backup/work": ["auto-2019-10-15_13-00", "auto-2019-10-15_09-00"],
    "backup/games": ["auto-2019-10-15_13-00"],
}

Update a Replication Task with specific id

See the documentation for create method for information on payload contents

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "replication.update",
    "params": [
        7,
        {
            "name": "Work Backup",
            "direction": "PUSH",
            "transport": "SSH",
            "ssh_credentials": [12],
            "source_datasets", ["data/work"],
            "target_dataset": "repl/work",
            "recursive": true,
            "periodic_snapshot_tasks": [5],
            "auto": true,
            "restrict_schedule": {
                "minute": "0",
                "hour": "*/2",
                "dom": "*",
                "month": "*",
                "dow": "1,2,3,4,5",
                "begin": "09:00",
                "end": "18:00"
            },
            "only_matching_schedule": true,
            "retention_policy": "CUSTOM",
            "lifetime_value": 1,
            "lifetime_unit": "WEEK",
        }
    ]
}

max_parallel_replication_tasks represents a maximum number of parallel replication tasks running.

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).

Get graph data of "nfsstat" from the last hour.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "reporting.get_data",
    "params": [
        [{"name": "nfsstat"}],
        {"unit": "HOURLY"},
    ]
}

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.

Update reporting settings

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "reporting.update",
    "params": [{
        "cpu_in_percentage": false,
        "graphite": "",
    }]
}

Recreate reporting database with new settings

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "reporting.update",
    "params": [{
        "graph_age": 12,
        "graph_points": 1200,
        "confirm_rrd_destroy": true,
    }]
}

Get the IPv4 gateway and verify if it is reachable by any interface.

Returns: bool: True if the gateway is reachable or otherwise False.

Get current/applied network routes.

Update Rsyncd Service Configuration.

auxiliary attribute can be used to pass on any additional parameters from rsyncd.conf(5).

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).

Delete Rsyncmod module of id.

Update Rsyncmod module of id.

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.

Create a Rsync Task which pulls data from a remote system every 5 minutes.

{
    "id": "6841f242-840a-11e6-a437-00e04d680384",
    "msg": "method",
    "method": "rsynctask.create",
    "params": [{
        "enabled": true,
        "schedule": {
            "minute": "5",
            "hour": "*",
            "dom": "*",
            "month": "*",
            "dow": "*"
        },
        "desc": "Test rsync task",
        "user": "root",
        "mode": "MODULE",
        "remotehost": "root@192.168.0.10",
        "compress": true,
        "archive": true,
        "direction": "PULL",
        "path": "/mnt/vol1/rsync_dataset",
        "remotemodule": "remote_module1"
    }]
}

Delete Rsync Task of id.

Job to run rsync task of id.

Output is saved to job log excerpt (not syslog).

Update Rsync Task of id.

Return ip choices for S3 service to use.

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.

Query all system services with query-filters and query-options.

Reload the service specified by service.

Restart the service specified by service.

Start the service specified by service.

Test if service specified by service has been started.

Stop the service specified by service.

Terminate process by pid.

First send TERM signal, then, if was not terminated in timeout seconds, send KILL signal.

Returns true is process has been successfully terminated with TERM and false if we had to use KILL.