Trouble installing TrueNAS API Client on Debian 13 VM

TrueNAS General
1

I am running a Virtual Machine that has Debian 13 as its OS, and acting as my Web / Proxy server to the outside world, including managing my SSL certs.

In the past, I would use deploy_freenas.py to push a cert to my TrueNAS when the cert was renewed. With the new API on the way, I wanted to move to deploy_truenas.py instead.

After following the instructions from DanB’s GitHub, the script is downloaded and configured, and I think the TrueNAS API client is installed, but I’m getting the following error:

root@virtualmin:~# /root/scripts/deploy_truenas/deploy_truenas.py
Traceback (most recent call last):File “/root/scripts/deploy_truenas/deploy_truenas.py”, line 28, in from truenas_api_client import ClientModuleNotFoundError: No module named ‘truenas_api_client’

root@virtualmin:~# pipx install git+https://github.com/truenas/api_client.git
'truenas_api_client’ already seems to be installed. Not modifying existing installation in‘/root/.local/share/pipx/venvs/truenas-api-client’. Pass ‘–force’ to force installation.

root@virtualmin:~# /root/scripts/deploy_truenas/deploy_truenas.py
Traceback (most recent call last):File “/root/scripts/deploy_truenas/deploy_truenas.py”, line 28, in from truenas_api_client import ClientModuleNotFoundError: No module named ‘truenas_api_client’

root@virtualmin:~#
2

Further information:

root@virtualmin:~# pip install git+https://github.com/truenas/api_client.git
error: externally-managed-environment

× This environment is externally managed╰─> To install Python packages system-wide, try apt installpython3-xyz, where xyz is the package you are trying to install.

If you wish to install a non-Debian-packaged Python package, create a virtual environment using python3 -m venv path/to/venv. Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make sure you have python3-full installed.  If you wish to install a non-Debian packaged Python application, it may be easiest to use pipx install xyz, which will manage a virtual environment for you. Make sure you have pipx installed.  See /usr/share/doc/python3.13/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.

hint: See PEP 668 for the detailed specification.

root@virtualmin:~# apt install python3

python3 is already the newest version (3.13.5-1).
Summary:
Upgrading: 0, Installing: 0, Removing: 0, Not Upgrading: 0

root@virtualmin:~#
3

Have a look at tnascert-deploy. It’s written in Go and the compiled binaries have no external dependencies. See the GitHub Repository. Pre-compiled binaries are available at tnascert-deploy version 2.0

1 Like
4

I’m inclined to agree, especially after iX have apparently deprecated the setup.py installation for the Python client. If you’re looking to run my script on the NAS itself, it’d be fine, but on a remote system it seems to be increasingly difficult to get the Python client installed in a way that would be usable.

5

It looks like tnascert-deploy is working. Thank you!

1 Like
6

Which API did you end up using with tnascert-deploy? Did you have any trouble with the configuration or was the documentation ok?

7

I have it on REST for the moment, but should update it for Web Sockets - I didn’t catch that, thank you for pointing it out!

8

That only applies if you’re installing master branch. GitHub - truenas/api_client at stable/goldeye

Generally you should try to match up to the version you’re using (or at least not track master).

Installing from master branch of a git repo is like running nightlies.

9

Since this is debian you could also in theory just download our debian package we distribute on our downloads page: https://download.truenas.com/TrueNAS-SCALE-Goldeye/25.10.0.1/packages/python3-truenas-api-client_20251114160447~truenas+1_all.deb

10

You’re ok using REST. You’ll need to upgrade to TrueNAS SCALE 25+ before switching to the websocket API.

11

Websocket API works generally all the way back to FreeNAS 11.3. The only thing that changed in 25.04 and later was URI for connections.

12

I’m on 25.10.0.1 - Goldeye now.

Here’s my config - I have two “devices” that are the same physical device, one is REST and one is WebSockets:

[restapi]
api_key = (SuperSecretAPIKey)
client_api = restapi
private_key_path = /home/aiskon/ssl.key
cert_basename = letsencrypt
full_chain_path = /home/aiskon/ssl.cert
connect_host = truenas.aiskon.net
protocol = https
tls_skip_verify = true
delete_old_certs = true
add_as_ui_certificate = true
add_as_ftp_certificate = false
add_as_app_certificate = false
timeoutSeconds = 10
debug = false

[wsapi]
api_key = (SuperSecretAPIKey)
client_api = wsapi
private_key_path = /home/aiskon/ssl.key
cert_basename = letsencrypt
full_chain_path = /home/aiskon/ssl.cert
connect_host = truenas.aiskon.net
protocol = wss
tls_skip_verify = true
delete_old_certs = true
add_as_ui_certificate = true
add_as_ftp_certificate = false
add_as_app_certificate = false
timeoutSeconds = 10
debug = false

When I run the REST version, it works fine. When I run the WebSockets version, I get an error:

root@virtualmin:~# /root/scripts/tnascert-deploy/tnascert-deploy -c /root/scripts/tnascert-deploy/tnas-cert.ini restapi           

2025/12/05 09:39:24 processing certificate installation for 'restapi'
2025/12/05 09:39:25 truenas.aiskon.net is running version '25.10.0.1'
2025/12/05 09:39:25 certificate verification: x509: certificate signed by unknown authority
2025/12/05 09:39:25 importing the letsencrypt-2025-12-05-1764945565 certificate
2025/12/05 09:39:30 successfully imported the letsencrypt-2025-12-05-1764945565 certificate
2025/12/05 09:39:39 updated the active UI certificate to use letsencrypt-2025-12-05-1764945565
2025/12/05 09:39:44 deleting old certificates with prefix 'letsencrypt'
2025/12/05 09:39:44 skip the deletion of the active UI certificate letsencrypt-2025-12-05-1764945565
2025/12/05 09:39:44 deleted certificate letsencrypt-2025-12-05-1764942707
2025/12/05 09:39:44 successfully deleted old certificates
2025/12/05 09:39:44 post installation tasks error, failed to restart the UI

root@virtualmin:~# /root/scripts/tnascert-deploy/tnascert-deploy -c /root/scripts/tnascert-deploy/tnas-cert.ini wsapi  

2025/12/05 09:39:50 processing certificate installation for 'wsapi'
2025/12/05 09:39:51 error creating client for 'wsapi': error: failed to connect: tls: failed to verify certificate: x509: certificate signed by unknown authority

root@virtualmin:~#
13

Hmm, it’s acting like your on Electric Eel 24.10 which requires the REST api. What’s odd to me is the 2nd line of your log:

2025/12/05 09:39:25 truenas.aiskon.net is running version '25.10.0.1'

Here is the log output from my TrueNAS-SCALE goldeneye 25.10.0.1 machine, NOTE the TrueNAS version string:

2025/12/05 08:05:20 processing certificate installation for 'nas02'
2025/12/05 08:05:21 nas02.alisa.org is running version 'TrueNAS-SCALE-25.10.0.1'
2025/12/05 08:05:21 certificate verified successfully
2025/12/05 08:05:21 importing the letsencrypt-2025-12-05-1764950721 certificate
2025/12/05 08:05:21 started the certificate creation job with ID: 41209
2025/12/05 08:05:22 job completed successfully!
2025/12/05 08:05:22 found the new certificate, letsencrypt-2025-12-05-1764950721, id: 343
2025/12/05 08:05:22 certificate letsencrypt-2025-12-05-1764950721 deployed successfully
2025/12/05 08:05:22 nas02.alisa.org is running version 'TrueNAS-SCALE-25.10.0.1'
2025/12/05 08:05:24 the FTP service certificate updated successfully to letsencrypt-2025-12-05-1764950721
2025/12/05 08:05:24 processing certificate update for the 'grafana' application
2025/12/05 08:05:24 started the app update job with ID: 41213
2025/12/05 08:05:26 job completed successfully!
2025/12/05 08:05:26 updated the certificate for app: grafana to use: letsencrypt-2025-12-05-1764950721, id: 343
2025/12/05 08:05:26 deleting old certificate letsencrypt-2025-11-26-1764223014, with job ID: 41215
2025/12/05 08:05:27 job completed successfully, certificate letsencrypt-2025-11-26-1764223014 was deleted
2025/12/05 08:05:27 deleting old certificate letsencrypt-2025-11-27-1764227313, with job ID: 41217
2025/12/05 08:05:28 job completed successfully, certificate letsencrypt-2025-11-27-1764227313 was deleted
2025/12/05 08:05:28 restarted the UI

This is weird to me, but I’ll try to duplicate it. For now stay with the REST API. Can you send the output from:

tnascert-deploy -v

It should be:

tnascert-deploy -v

release: 2.0
git revision: d125c8c9078be8db3dc92c6a34f2c2c597263a4b

John

14

In your configuration for ‘wsapi’, can you add in the port your using, ie 443, and retry.

15

Hm, I am getting:

root@virtualmin:~/scripts/tnascert-deploy# ./tnascert-deploy -v 

release: 2.0
git revision: bea9388ca730c3320aafb3f9a9cdeeccae94020c

root@virtualmin:~/scripts/tnascert-deploy#
16

When I add 443 to the hostname, I am getting:

root@virtualmin:~/scripts/tnascert-deploy# /root/scripts/tnascert-deploy/tnascert-deploy -c /root/scripts/tnascert-deploy/tnas-cert.ini wsapi

2025/12/05 12:03:29 processing certificate installation for 'wsapi'
2025/12/05 12:03:29 error creating client for 'wsapi': error: failed to connect: dial tcp: address truenas.aiskon.net:443:443: too many colons in address

root@virtualmin:~/scripts/tnascert-deploy#
17

don’t add it to the hostname, instead add ‘port = 443’ to your configuration.

18

thia Is fine

19

Same error:

root@virtualmin:~/scripts/tnascert-deploy# /root/scripts/tnascert-deploy/tnascert-deploy -c /root/scripts/tnascert-deploy/tnas-cert.ini wsapi

2025/12/05 12:58:21 processing certificate installation for 'wsapi'
2025/12/05 12:58:21 error creating client for 'wsapi': error: failed to connect: tls: failed to verify certificate: x509: certificate signed by unknown authority

root@virtualmin:~/scripts/tnascert-deploy#
20

It’s failing to connect, what happens if you use a browser to connect to https://truenas.aiskon.net/api/current

You should get:

No WebSocket UPGRADE hdr: None
 Can "Upgrade" only to "WebSocket".