New Features Coming to Asadm — Aerospike’s Admin Tool
Tags: aerospike, nosql, database, tooling
Published: 2021-02-23 01:29:42


![Photo by [NeONBRAND](https://unsplash.com/@neonbrand?utm_source=medium&utm_medium=referral) on [Unsplash](https://unsplash.com?utm_source=medium&utm_medium=referral)](https://miro.medium.com/max/1400/0*RtxsWDsf4gIldyGi)Photo by [NeONBRAND](https://unsplash.com/@neonbrand?utm_source=medium&utm_medium=referral) on [Unsplash](https://unsplash.com?utm_source=medium&utm_medium=referral)

## **Aerospike Admin (Asadm)**

[Asadm](https://www.aerospike.com/docs/tools/asadm/index.html) 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

1. Add and remove UDFs

1. 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](https://www.aerospike.com/docs/reference/configuration/index.html#enable-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](https://unsplash.com/@martinadams?utm_source=medium&utm_medium=referral) on [Unsplash](https://unsplash.com?utm_source=medium&utm_medium=referral)](https://cdn-images-1.medium.com/max/6124/0*HbsS9cVnfYIsG6zZ)*Photo by [Martin Adams](https://unsplash.com/@martinadams?utm_source=medium&utm_medium=referral) on [Unsplash](https://unsplash.com?utm_source=medium&utm_medium=referral)*

**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](https://unsplash.com/@jdent?utm_source=medium&utm_medium=referral) on [Unsplash](https://unsplash.com?utm_source=medium&utm_medium=referral)](https://cdn-images-1.medium.com/max/5514/0*ziZ9p2MCVAmxqIwF)*Photo by [Jason Dent](https://unsplash.com/@jdent?utm_source=medium&utm_medium=referral) on [Unsplash](https://unsplash.com?utm_source=medium&utm_medium=referral)*

**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](https://www.aerospike.com/docs/operations/configure/security/access-control/) in the Aerospike technical documentation.

To use the new `manage acl` commands we must first make sure [security](https://www.aerospike.com/docs/reference/configuration/index.html#enable-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!