New Features Coming to Asadm — Aerospike’s Admin Tool

Photo by NeONBRAND on Unsplash

Aerospike Admin (Asadm)

Asadm used to be Aerospike Database’s primary tool for monitoring performance and configuration, but it now has the ability to do common administrative tasks. Funnily enough, until now, Aerospike users would need to use another tool, aql, to do everyday administrative tasks like create a new user or update a user-defined function (UDF). With the latest Aerospike Tools 5.1.0, asadm will have the ability to:

1. Manage user and roles

2. Add and remove UDFs

3. Create and delete secondary indexes (sindexes)

As well as some other convenient features I will touch on later.

A Suite of New manage Commands to Administer your Aerospike Database

Admin+> manage acl create user superwoman roles sys-admin
Enter password for new user superwoman:
Successfully created user superwoman.
Admin+>
Admin+> show users
~~~~~~Users (2021-02-18 20:49:01 UTC)~~~~~~~
      User|                            Roles
admin     |read-write, sys-admin, user-admin
superwoman|                        sys-admin
Number of rows: 2

To access the new feature set, there is a new manage command. The manage command, you guessed it, helps you manage your users, roles, sindexes, and UDFs. There are quite a few manage sub-commands, which I will cover later on with some examples, but from a top-level view, there is manage sindex, manage udfs, and manage acl (access control list). The new manage commands are also accompanied by a new show commands show users, show roles, show udfs, and show sindex. Together, the show and manage commands can be used to administer your Aerospike Database with ease.

A New Privileged Mode in Asadm

Admin> asinfo -v build
ERROR: User must be in privileged mode to issue "asinfo"
       commands.
       Type "enable" to enter privileged mode.
Admin> enable
Admin+> asinfo -v build
ubuntu:3000 (192.168.173.203) returned:
5.4.0.3

Unlike existing asadm commands that monitor Aerospike’s DB state, the manage commands mutate data in the database, which adds a level of risk not seen before in asadm. There is an exception: the asinfo command, which allows some unfettered access to the Aerospike Database. A new “privileged” mode has been created, allowing users to access any risky commands like asinfo and asadm’s new suite of manage commands. The privileged mode is intended to keep users from inadvertently making changes to the Aerospike Database. The enable command also changes the prompt from Admin> to Admin+> to signify the added risk.

Admin> enable --warn
Admin+> manage sindex delete age-index ns test
The secondary index age-index has 654 keys indexed.
Confirm that you want to proceed by typing x4b862, or 
cancel by typing anything else.
x4b862
Successfully deleted sindex age-index.
Admin+>

Privileged mode has another level of protection added by the --warn flag, which, when possible, tries to inform you of the implications of the command. In the example above, you can see the manage sindex delete command informs the user about the number of keys currently stored in the index and requires a random six-digit hex code to continue.

To exit privileged mode and be kept from issuing asinfo or manage commands, use the disable command.

Now let's look at some examples.

Before we begin

Using Aerospike Enterprise Edition (EE) with security enabled requires the data-admin credential for manage udf and manage sindex commands. Similarly, to use the manage acl commands you must have the user-admin credential.

Managing User-Defined Functions (UDF)

There are two commands available for UDF management, manage udfs add and manage udfs remove. First, let's add a UDF module to the Aerospike DB.

Admin> enable
Admin+> manage udfs add foo.lua path path/to/foo.lua
Successfully added UDF foo.lua.

Let’s verify with the new show udf command.

Admin+> show udfs
~~~~~~~~~~UDF Modules (2021-02-18 01:11:39 UTC)~~~~~~~~~~~
    Filename|                                    Hash|Type
abc.123     |dceaf7f1acddf1d6e12a1752d499d80cfadfc24b|LUA 
bar.lua     |591d2536acb21a329040beabfd9bfaf110d35c18|LUA 
foo.lua     |f6eaf2b22d8b29b3597ef1ad9113d0907425ecd0|LUA 
mymodule.lua|7fae110826972135a3c3b8a812d43243e7c7a23c|LUA 
test.lua    |9f78214b275e306596d8e7120103585f3ee6adcc|LUA 
Number of rows: 5

We can then enter privileged mode with the --warn flag and update a UDF module.

Admin+> disable
Admin> enable --warn
Admin+> manage udfs add bar.lua path test.lua
You are about to write over an existing UDF module.
Confirm that you want to proceed by typing 6a9cb8, or
cancel by typing anything else.
6a9cb8
Successfully added UDF bar.lua.

As you can see, asadm first checks if the UDF module already existed and warned that it would be overwritten by running the command. Lastly, let’s delete a UDF module.

Admin+> manage udfs remove foo.lua
You are about to remove a UDF module that may be in use.
Confirm that you want to proceed by typing 1629e6, or
cancel by typing anything else.
1629e6
Successfully removed UDF foo.lua.

Again, asadm first prompts you to make sure that you understand the risks of issuing a command to remove a UDF.

Photo by Martin Adams on Unsplash

Managing Secondary Indexes

There are two new commands available for sindex management. They are manage sindex create and manage sindex delete. Let’s assume we have some data in the namespace “bar” and the set “testset” with the basic structure below.

PK   | name  | age
------------------
key1 | Jack  | 26
key2 | Jill  | 20
key3 | Sean  | 26
key4 | Sally | 24

Now let’s create a numeric sindex on bin “age”.

Admin+> manage sindex create numeric age-index ns bar set testset bin age
Adding a secondary index will cause longer restart times.
Confirm that you want to proceed by typing 52bf49, or
cancel by typing anything else.
52bf49
Successfully created sindex age-index.

Notice the warning provided by asadm. Next, we verify using the new show sindex command.

Admin+> show sindex
~~~~Secondary Indexes (2021-02-18 01:52:46 UTC)~~~~
    Index|Namespace|    Set|Bin|    Bin|Index|State
     Name|         |       |   |   Type| Type|     
age-index|bar      |testset|age|NUMERIC|NONE |RW   
Number of rows: 1

Now let’s delete the sindex since we no longer need it, and it causes longer restart times.

Admin+> manage sinde delete age-index ns bar
The secondary index age-index has 10 keys indexed.
Confirm that you want to proceed by typing 5ec3e3, or
cancel by typing anything else.
5ec3e3
Successfully deleted sindex age-index.

And there you have it. You can now manage your sindexes without breaking a sweat!

Photo by Jason Dent on Unsplash

Managing the Access Control List (ACL)

Configuring your ACL is essential to keeping unwanted users out of your Enterprise Edition of Aerospike Database. In Aerospike EE, users are assigned roles, and roles are assigned privileges. Note that privileges are predefined for you and cannot be changed. You can read more about configuring access control in the Aerospike technical documentation.

To use the new manage acl commands we must first make sure security is enabled in our aerospike.conf file. The default location of the config file is /etc/aerospike/aerospike.conf. To log in with your credential run asadm -U <username> and you will be prompted for your password. If you are just getting started with your Aerospike DB then the default username and password is admin, admin (be sure to change your password using the new set-password command below). As stated previously, manage acl commands require the user-admin credential.

Now on to an example.

First, let’s create a user named Fred Rogers.

Admin> enable
Admin+> manage acl create user Mr-Rogers
Enter password for new user Mr-Rogers:
Successfully created user Mr-Rogers.

To verify that we created the user, let’s use the new show users command.

Admin+> show users
~~~~~~Users (2021-02-18 00:23:40 UTC)~~~~~~
     User|                            Roles
Mr-Rogers|                               --
admin    |read-write, sys-admin, user-admin
Number of rows: 2

And there he is, but he has no roles. Now let's create a few roles.

Admin+> manage acl create role Bad-Neighbor priv read ns test set testset
Successfully created role Bad-Neighbor.
Admin+>
Admin+> manage acl create role Good-Neighbor priv sys-admin
Successfully created role Good-Neighbor.

The first role is “Bad-Neighbor,” which has the read privilege but only for the namespace “test” and set “testset”. The second privilege is named “Good-Neighbor” and has the privilege sys-admin, which is globally applied.

Now let’s verify with the new show roles command.

Admin+> show roles
~Roles (2021-02-18 00:35:02 UTC)~
          Role|       Privileges
Bad-Neighbor  |read.test.testset
Good-Neighbor |        sys-admin
data-admin    |       data-admin
read          |             read
read-write    |       read-write
read-write-udf|   read-write-udf
sys-admin     |        sys-admin
user-admin    |       user-admin
write         |            write
Number of rows: 9

There they are! Now let's assign those roles to Mr-Rogers.

Admin+> manage acl grant user Mr-Rogers roles Good-Neighbor Bad-Neighbor
Successfully granted roles to user Mr-Rogers.
Admin+>
Admin+> show users
~~~~~~Users (2021-02-18 00:39:00 UTC)~~~~~~
     User|                            Roles
Mr-Rogers|        Bad-Neighbor, Good-Neighbor
admin    |read-write, sys-admin, user-admin
Number of rows: 2

But that doesn’t look right?!?! After all, Mr-Rogers was a good neighbor. Let’s revoke the role “Bad-Neighbor” from Mr-Rogers.

Admin+> manage acl revoke user Mr-Rogers roles Bad-Neighbor
Successfully revoked roles from user Mr-Rogers.
Admin+>
Admin+> show users
~~~~~~Users (2021-02-18 00:43:00 UTC)~~~~~~
     User|                            Roles
Mr-Rogers|                     Good-Neigbor
admin    |read-write, sys-admin, user-admin
Number of rows: 2

Ahhh, that’s better. Although, we still have a bad neighbor lurking around. Let’s restrict Bad-Neighbor's access even more by issuing the role an allowlist. That is, addresses Bad-Neighbor can connect from.

Admin+> manage acl allowlist role Bad-Neighbor allow 192.168.2.1
Successfully updated allowlist for role Bad-Neighbor.
Admin+> show roles
~~~~~~Roles (2021-02-18 00:47:34 UTC)~~~~~~~
          Role|       Privileges|  Allowlist
Bad-Neighbor  |read.test.testset|192.168.2.1
Good-Neighbor |        sys-admin|         --
data-admin    |       data-admin|         --
read          |             read|         --
read-write    |       read-write|         --
read-write-udf|   read-write-udf|         --
sys-admin     |        sys-admin|         --
user-admin    |       user-admin|         --
write         |            write|         --
Number of rows: 9

Now we have another column of allowlist that is returned by show roles. “Bad-Neighbor” will only be able to connect from the address 192.168.2.1.

Asadm is your new one-stop-shop

As you can see asadm is coming closer to be the singular tool required to monitor, administer, and configure your Aerospike Database. Now, you no longer are required to use aql when you need to manage users and roles, add and remove UDFs, and create and delete secondary indexes. There are also plans in the works to add more features to make interacting with your Aerospike Database easier than ever before, so please stay tuned!