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:
Manage user and roles
Add and remove UDFs
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 udfs, and
manage acl (access control list). The new manage commands are also accompanied by a new show commands
show udfs, and
show sindex. Together, the
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: 126.96.36.199
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 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
manage commands, use the
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
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.
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!
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
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
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!