Skip to content

10. nxctl: Nexus command line

Jump to bottom
Roger Zaragoza edited this page Nov 11, 2016 · 1 revision

nxctl

nxctl is a command line tool developed to interact with Nexus. It allows you to perform administrative actions (like creating users or assigning permissions) as well as interacting with running services using task or topic methods as you will see in the following examples.

Download

Sources for the command line can be found at github:

https://github.com/nayarsystems/nxctl

And release binaries for multiple platforms can be downloaded from:

https://github.com/nayarsystems/nxctl/releases

Help

$ nxctl -h
usage: nxctl [<flags>] <command> [<args> ...]

Nexus command line interface

Flags:
  -h, --help             Show context-sensitive help (also try --help-long and --help-man).
  -s, --server=SERVER    Server address.
  -t, --timeout=TIMEOUT  Execution timeout
  -u, --user=USER        Nexus username
  -p, --pass=PASS        Nexus password
  -c, --config=CONFIG    Config filename
      --ignoreapi        Ignore API version check

Commands:
  help [<command>...]
  shell
  login <username> <password>
  push <method> [<params>...]
  pushj <method> <json {param:value,...}>
  pull <prefix>
  list [<flags>] [<prefix>]
  pipe
    read
    open <pipeId> <data>...
  user
    create <username> <password>
    delete <username>
    passwd <username> <password>
    list [<flags>] [<prefix>]
    kick <prefix>
    reload <prefix>
    max-sessions <username> <max>
  sessions
    list [<flags>] [<prefix>]
    kick <connId>
    reload <connId>
  nodes [<flags>]
  tags
    set <user> <prefix> [<tags>...]
    setj <user> <prefix> <json {tag:value,...}>
    del <user> <prefix> <tags>...
  template
    add <user> <template>
    del <user> <template>
  whitelist
    add <user> <ip>
    del <user> <ip>
  blacklist
    add <user> <ip>
    del <user> <ip>
  topic
    sub <pipe> <topic>
    unsub <pipe> <topic>
    pub <topic> <data>...

Environment files

nxctl supports different environment definition files, so you can issue commands as different users and against different instances of nexus.

If no environment file is found, you can still pass this info to nxctl via flags on each execution.

The environment files must be stored in one of the following paths:

  • /etc/nxctl/
  • $HOME
  • $HOME/.nxctl
  • $HOME/.config/nxctl
  • $HOME/.local/config/nxctl
  • $HOME/%APPDATA%/nxctl

And must be defined either in JSON or YML formats, defining values for:

  • user
  • password
  • server

Having defined some environment files, you can use the -c or *--config" command line option to specify which environment to use. If you create an environment file called default (default.json or default.yml), those values will be used by default when no option is used.

Creating a default environment file

Let's create a default environment file to login as root to our local running Nexus instance. We will create it in $HOME/.nxctl directory with JSON format.

Use your preferred editor to create a $HOME/.nxctl/default.json file with the following contents:

{
	"user": "root",
	"password": "root",
	"server": "tcp://localhost:1717"
}

Now we can execute nxctl commands without passing flags and this configuration will be used. We could create another file, let's say $HOME/.nxctl/demo.json that defines another user and use it executing commands with nxctl -c demo.

Using nxctl

Some of the following commands must be launched in different terminals because you will be simulating multiple distributed components. Some actions like a pull are blocked until another session makes a push.

User administration

Create a user
$ nxctl user create demo demo
2016/11/10 07:37:53 Logged as root
2016/11/10 07:37:53 Creating user "demo" with password "demo"
2016/11/10 07:37:53 OK
Delete a user
$ nxctl user delete demo
2016/11/10 07:37:54 Connected to 127.0.0.1:1717
2016/11/10 07:37:54 Logged as root
2016/11/10 07:37:54 Deleting user "demo"
2016/11/10 07:37:54 OK
Change user password
$ nxctl user passwd demo newpass
2016/11/10 07:42:38 Connected to 127.0.0.1:1717
2016/11/10 07:42:38 Logged as root
2016/11/10 07:42:38 OK
List users

Let's imagine we have created some users:

  • demo
  • admins.service1.user1
  • admins.service1.user2
  • admins.service2.user1
  • admins.service2.user2
  • clients.service1.user1
  • clients.service1.user2
  • clients.service2.user1
  • clients.service2.user2

List admins of service1:

$ nxctl user list admins.service1
2016/11/10 08:00:13 Connected to tcp://localhost:1717
2016/11/10 08:00:13 Logged as root
2016/11/10 08:00:13 Listing users on "admins.service1"
          USER          | TEMPLATES | WHITELIST | BLACKLIST | MAX SESSIONS | PREFIX | TAGS  
+-----------------------+-----------+-----------+-----------+--------------+--------+------+
  admins.service1.user2 |    []     |    []     |    []     |      50      |        |       
+-----------------------+-----------+-----------+-----------+--------------+--------+------+
  admins.service1.user1 |    []     |    []     |    []     |      50      |        |       
+-----------------------+-----------+-----------+-----------+--------------+--------+------+

List all users:

$ nxctl user list
2016/11/10 08:01:29 Connected to tcp://localhost:1717
2016/11/10 08:01:29 Logged as root
2016/11/10 08:01:29 Listing users on ""
           USER          | TEMPLATES | WHITELIST | BLACKLIST | MAX SESSIONS | PREFIX |       TAGS        
+------------------------+-----------+-----------+-----------+--------------+--------+------------------+
  clients.service2.user1 |    []     |    []     |    []     |      50      |        |                   
+------------------------+-----------+-----------+-----------+--------------+--------+------------------+
  admins.service1.user2  |    []     |    []     |    []     |      50      |        |                   
+------------------------+-----------+-----------+-----------+--------------+--------+------------------+
  clients.service2.user2 |    []     |    []     |    []     |      50      |        |                   
+------------------------+-----------+-----------+-----------+--------------+--------+------------------+
  admins.service2.user2  |    []     |    []     |    []     |      50      |        |                   
+------------------------+-----------+-----------+-----------+--------------+--------+------------------+
  clients.service1.user2 |    []     |    []     |    []     |      50      |        |                   
+------------------------+-----------+-----------+-----------+--------------+--------+------------------+
  admins.service1.user1  |    []     |    []     |    []     |      50      |        |                   
+------------------------+-----------+-----------+-----------+--------------+--------+------------------+
  admins.service2.user1  |    []     |    []     |    []     |      50      |        |                   
+------------------------+-----------+-----------+-----------+--------------+--------+------------------+
  clients.service1.user1 |    []     |    []     |    []     |      50      |        |                   
+------------------------+-----------+-----------+-----------+--------------+--------+------------------+
           demo          |    []     |    []     |    []     |      50      |        |                   
+------------------------+-----------+-----------+-----------+--------------+--------+------------------+
           root          |    []     |    []     |    []     |      50      |   .    | map[@admin:true]  
+------------------------+-----------+-----------+-----------+--------------+--------+------------------+
Setting tags on users

The following command will give the permission to call task.push on the path some.service.path to the user demo.

$ nxctl tags setj demo some.service.path '{"@task.push": true}'
2016/11/10 08:09:43 Connected to tcp://localhost:1717
2016/11/10 08:09:43 Logged as root
2016/11/10 08:09:43 Setting tags: map[@task.push:true] on [email protected]
2016/11/10 08:09:43 OK

Other operations on users

  • nxctl user max-sessions demo 100 sets the number of maximum active sessions for demo to 100.
  • nxctl whitelist add demo 1.2.3.4 adds IP 1.2.3.4 to the whitelist of the demo user, allowing connections from that IP to nexus.
  • nxctl blacklist add demo 4.3.2.1 adds IP 4.3.2.1 to the blacklist of the demo user, denying connections from that IP to nexus.
  • nxctl template add demo other.user adds the user other.user as a template for demo user, coying all his tags.

Testing task push/pull

Pull: terminal 1

$ nxctl -u root -p root pull my.demo.path
2016/10/05 13:13:46 Logged as root
2016/10/05 13:13:46 Pulling my.demo.path

This call blocks waiting for a task.push.

Push: terminal 2

$ nxctl -u root -p root pushj my.demo.path.method '{"dummy": "param"}'
2016/10/05 13:13:49 Logged as root

This call blocks waiting for a task.result or task.error.

Pull: terminal 1

{
  "Path": "my.demo.path.",
  "Method": "method",
  "Params": {"dummy": "param"},
  "Prio": 0,
  "Detach": false,
  "User": "root",
  "Tags": {
    "@admin": true
  }
}
[R]esult or [E]rror? r
Result: Dummy response!

The puller receives the task and responds.

Push: terminal 2

2016/10/05 13:13:55 Result:
Dummy response!

The pusher receives the response.

Testing topic pub/sub

Reader: terminal 1

$ nxctl pipe read
2016/10/05 11:22:48 Connected to localhost
2016/10/05 11:22:48 Logged as root
2016/10/05 11:22:48 Pipe created: b6a7f085aeea0bfcd1fd0fb3434b024095ab

Reader is blocked waiting for messages on the pipe.

Subscriber: terminal 5

$ nxctl topic sub b6a7f085aeea0bfcd1fd0fb3434b024095ab nexus.example.topic
2016/10/05 11:24:50 Connected to localhost
2016/10/05 11:24:50 Logged as root
2016/10/05 11:24:50 OK

Now the pipe from the reader has been subscribed to an example topic.

Publisher 1: terminal 3

$ nxctl topic pub nexus.example.topic "my first pub"
2016/10/05 11:24:56 Connected to localhost
2016/10/05 11:24:56 Logged as root
2016/10/05 11:24:56 Result: map[ok:true sent:1]

Publisher 2: terminal 4

$ nxctl topic pub nexus.example.topic "my second pub"
2016/10/05 11:24:59 Connected to localhost
2016/10/05 11:24:59 Logged as root
2016/10/05 11:24:59 Result: map[ok:true sent:1]

As data is written to pipe, the reader receives it and is woken up.

2016/10/05 11:24:56 Got: map[msg:[my first pub] topic:nexus.example.topic] 1
...
2016/10/05 11:24:59 Got: map[msg:[my second pub] topic:nexus.example.topic] 1
Clone this wiki locally