Using websocket API to create a new smb share

Thibaut

Dabbler
Joined
Jun 21, 2014
Messages
33
Hello,

We have a server running FreeNAS 11.2-U3.
Since there doesn't seem to be a way to restrict feature access in the WebGUI, I've been writing some bash shell scripts that let users execute some specific operations without allowing them to access the whole system configuration options, thus avoiding the risk of inadvertent critical mistakes.

Up until now, I've been using curl to access the FreeNAS "legacy" RESTful 2.0 API.
Since it has been announced that a new websocket API is available, I've started exploring the possibility to interact with FreeNAS using this new method. Unfortunately the documentation on the subject is very scarce and, at the time being, usage examples are almost impossible to find.
I, of course, referred to the included API documentation available under http://my.free.nas.ip/api/docs. By the way, when using a non standard port for the FreeNAS Web GUI, the http://my.free.nas.ip:xxxxx/api/docs page shows an "Impossible to connect" error in the panels under the "Websocket" and "RESTful 2.0" tabs! One have to directly access the respective pages using their full URL (i.e.: http://my.free.nas.ip:xxxxx/api/docs/websocket and http://my.free.nas.ip:xxxxx/api/docs/restful/) in order to be able to consult those pages...

Anyway, the currently available websocket API documentation is absolutely minimal and has so far not allowed me to understand how to use it in order to send and receive useful commands and answers to and from the FreeNAS system.

What I've been able to achieve is:
  • Create a dedicated user on the FreeNAS system that has the necessary access rights to execute the required bash script commands
  • Install a FreeBSD compatible pre-built binary of the Websocat library (since packages cannot be installed on the read-only FreeNAS system)
  • Use the websocat command to connect to the FreeNAS websocket API
  • Issue the first FreeNAS websocket commands to initiate the API connection
Here is a sample of how this translates into command line code:
Code:
[apiuser@freenas ~]$ websocat ws://my.free.nas.ip:port/websocket
{"msg": "connect", "version": "1","support": ["1"]}
{"msg": "connected", "session": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}
{"msg": "method", "method": "auth.login", "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "params":["root","***********"]}
{"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "msg": "result", "result": true}

I could then issue simple API calls like the following:
Code:
{"msg": "method", "method": "alert.list", "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}
{"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "msg": "result", "result": [{"title": "New feature flags are available for volume %s. Refer to the \"Upgrading a ZFS Pool\" subsection in the User Guide \"Installing and Upgrading\" chapter and \"Upgrading\" section for more instructions.", "args": "Pool1", "source": "VolumeVersion", "node": "A", "key": "[\"New feature flags are available for volume %s. Refer to the \\\"Upgrading a ZFS Pool\\\" subsection in the User Guide \\\"Installing and Upgrading\\\" chapter and \\\"Upgrading\\\" section for more instructions.\", \"Pool1\"]", "datetime": {"$date": 1549731647330}, "level": "WARNING", "dismissed": false, "mail": null, "id": "A;VolumeVersion;[\"New feature flags are available for volume %s. Refer to the \\\"Upgrading a ZFS Pool\\\" subsection in the User Guide \\\"Installing and Upgrading\\\" chapter and \\\"Upgrading\\\" section for more instructions.\", \"Pool1\"]", "formatted": "New feature flags are available for volume Pool1. Refer to the \"Upgrading a ZFS Pool\" subsection in the User Guide \"Installing and Upgrading\" chapter and \"Upgrading\" section for more instructions."}, {"title": "The capacity for the volume \"%(volume)s\" is currently at %(capacity)d%%, while the recommended value is below 80%%.", "args": {"volume": "Pool1", "capacity": 84}, "source": "ZpoolCapacity", "node": "A", "key": "[\"Pool1\", \"WARNING\"]", "datetime": {"$date": 1549731633262}, "level": "WARNING", "dismissed": false, "mail": null, "id": "A;ZpoolCapacity;[\"Pool1\", \"WARNING\"]", "formatted": "The capacity for the volume \"Pool1\" is currently at 84%, while the recommended value is below 80%."}]}

Now, since my script already contains the necessary code to create a new zfs dataset, my first objective would be to first list all existing smb shares to avoid duplicate share names, then issue the API call to create a new smb share...
Unfortunately I couldn't figure out how this should be formulated.

Any help on the subject would be greatly appreciated.

Best regards.
 
D

dlavigne

Guest
Were you able to figure this out? If not, it may be worth reporting at bugs.ixsystems.com so that the API docs can be clarified.
 
Top