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:
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: 2To 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 commandsshow 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.3Unlike 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: theasinfo 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 fromAdmin> 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+>If you are trying to run a manage or asinfo command from the cmd line you must prependenable; to enter privileged mode.
asadm -e ‘enable; manage sindex delete age-index ns test’Update: In Aerospike Tools 6.3.0 you can use the --enable flag to circumvent prepending the enable; command. The flag can be added to the astools.conf file or be provided via the cmd line. However, the flag is not supported in interactive mode.
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 udfs 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 udfs 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: 5We 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 aremanage 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 | 24Now 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: 1Now 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 aclcommands 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-passwordcommand 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 newshow 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: 2And 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: 9There 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: 2But 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: 2Ahhh, 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: 9Now 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!
