Found an issue? Please report it on our Jira bugtracker.
The TrueNAS websocket client provides the command line tool midclt and the means to easily communicate with middleware using Python by making calls through the websocket API. The client can connect to a local TrueNAS instance by default or to a specified remote socket. This offers an alternative to going through the web UI or connecting via ssh.
By default, communication facilitated by the API between the client and middleware now uses the JSON-RPC 2.0 protocol. However, it is still possible to use the legacy client by passing a legacy uri, e.g. 'ws://some.truenas.address/websocket' as opposed to 'ws://some.truenas.address/api/current'.
TrueNAS comes with this client preinstalled, but it is also possible to use the TrueNAS websocket client from a non-TrueNAS host.
On a non-TrueNAS host, ensure that Git is installed and run pip install git+https://github.com/truenas/api_client.git to automatically install dependencies. You may alternatively clone this repository and run python setup.py install. Using a Python venv is recommended.
The midclt command (not to be confused with the TrueNAS CLI) provides a way to make direct API calls through the client. To view its syntax, enter midclt -h. The -h option can also be used with any of midclt's subcommands.
The client's default behavior is to connect to the localhost's middlewared socket. For a remote connection, e.g. from a Windows host, you must specify the --uri option and authenticate with either user credentials or an API key. For example: midclt --uri ws://<TRUENAS_IP>/api/current -K key ...
root@my_truenas[~]# midclt call user.create '{"full_name": "John Doe", "username": "user", "password": "pass", "group_create": true}'
root@my_truenas[~]# midclt --uri ws://some.other.truenas/api/current -U user -P password call system.info
root@my_truenas[~]# midclt call -j pool.dataset.lock mypool/mydataset
The TrueNAS API client can also be used in Python scripts.
from truenas_api_client import Client
with Client() as c: # Local IPC
print(c.ping()) # pong
user = {"full_name": "John Doe", "username": "user", "password": "pass", "group_create": True}
entry_id = c.call("user.create", user)
user = c.call("user.get_instance", entry_id)
print(user["full_name"]) # John Doe# User account
with Client(uri="ws://some.other.truenas/api/current") as c:
c.call("auth.login", username, password)
# API key
with Client(uri="ws://some.other.truenas/api/current") as c:
c.call("auth.login_with_api_key", key)with Client() as c:
is_locked = c.call("pool.dataset.lock", "mypool/mydataset", job=True)
if is_locked:
args = {"datasets": [{"name": "mypool/mydataset", "passphrase": "passphrase"}]}
c.call("pool.dataset.unlock", "mypool/mydataset", args, job=True)