02. Start using nexus

Nexus basics

At this point Nexus should be running and ready to answer our requests (in the following examples we will assume it's listening on TCP port 1717).

When nexus starts for the first time, it has a root user with root password that has all the permissions, we will use this user in the following examples.

Nexus JSON-RPC protocol

Nexus just interprets JSON-RPC 2.0 calls that look like that:

{"jsonrpc":"2.0", "method": "<api-method>", "params": <api-params>, "id":<some-id>}

api-method and api-params are defined in the Nexus API document. While api-params is ommited in some API methods, api-method is always required.

some-id is a required field, it's usually a number that is returned with the response.

The response can be a result or an error. The results are documented in the Nexus API document document, and look like:

{"jsonrpc":"2.0", "result": <api-result>, "id":<some-id>}

The errors that can be returned are documented in the Nexus API document but they are not specified for each API method. However they tend to be self-explanatory. An error response looks like:

{"jsonrpc":"2.0", "error": {"code": <error-code>, "message": <error-message>, "data": <error-data>}, "id":<some-id>}

The limit for the size of each JSON-RPC message Nexus can accept is 32Mb.

Testing nexus JSON-RPC protocol

To show the simplicity of the nexus protocol, the following examples will open a TCP connection on port 1717 against nexus (using ncat) and call some methods.

Pro tip: executing ncat with rlwrap rlwrap ncat localhost 1717 allows to have command history and to edit the current line, so it's better to use it.

In the following examples, to distinguish between requests and responses, we prepend >>> to requests and <<< to responses, but you should not write nor see them.

¡Let's start! Connect to nexus.

$ ncat localhost 1717

Ok. Test if there's someone on the other side with sys.ping:

>>> {"jsonrpc":"2.0", "method": "sys.ping", "id":1}
<<< {"jsonrpc":"2.0", "result":{"ok":true}, "id":1}

¡Good! As nexus is connection-oriented, if you don't send anything to it after a watchdog time, it will close your connection. Clients use sys.ping to keep the connection alive if no other method is called in a while.

Let's query the watchdog time with a sys.watchdog call.

>>> {"jsonrpc":"2.0", "method": "sys.watchdog", "id":1}
<<< {"jsonrpc":"2.0", "result":{"watchdog":90}, "id":1}

The default watchdog time is 90 seconds, set it to 5 minutes.

>>> {"jsonrpc":"2.0", "method": "sys.watchdog", "params": {"watchdog": 300}, "id":1}
<<< {"jsonrpc":"2.0", "result":{"watchdog":300}, "id":1}

¡Done! This is pretty much all the methods you can call without doing a login. Let's call sys.login.

>>> {"jsonrpc":"2.0", "method": "sys.login", "params": {"user": "root", "pass":"root"}, "id":1}
<<< {"jsonrpc":"2.0", "result": {"ok": true, "connid": <some-connid>, "user": "root", "tags": {".": {"@admin": true}}, "id":1}

Here you logged to nexus and it answered with your connid that is unique to the session and it returned your user tags.

Tags are a key concept of Nexus users, they hold the permissions and any other data that wants to be associated to it. They are explained deeply later, but for now, if you are curious, the returned tags parameter states that user root has admin permission on all prefixes.

Now you should be able to call all the methods on the Nexus API document, ¡feel free to explore!

Using nexus command line (nxctl)

You shouldn't deal with JSON-RPC commands directly, so we built nxctl, a command line utility to call API methods the easy way.

Following examples will be done with the command line tool or with some client.