README ¶
NodeLocker
Building the project
As this project was developed and tested on x86_64 linux, I'm providing a simple shell script to make binary building easier. Please see ./build_linux.sh
in the project's root directory.
Running tests
⚠️ Please be aware that running the included ShellSpec tests WILL DESTROY ALL YOUR LOCAL REDIS DATABASE! Use it with extra caution!
The test definitions are inside tests/full_spec.sh
You can read more on ShellSpec format here: https://shellspec.info/
Run the tests from the project directory with the following command:
❯ shellspec tests/
Running NodeLocker
After compiling with ./build_linux.sh
the output binary will be at bin/release/nodelocker-linux
. When the local Redis database is ready, just run the compiled binary from there manually for testing.
❯ ./nodelocker-linux
Of course, the lab-prod behavior needs some extra setup, like a systemd module. I prefer supervisord for running such user-mode applications, your mileage may vary.
Just keep in mind, that if somehow the app fails, it won't restart itself, there is no watchdog feature implemented.
Getting started
Using NodeLocker
NodeLocker is a REST-like API service that is controllable via GET requests. For the sake of simplicity, POST, PUT and other methods are not used.
Administrator functions
General request format:
❯ https://example.local:3000/admin?action=<some_action>&name=<entity_name>&token=<admin_token>
<admin_token> is the passphrase token for the admin user. To generate a token, you can simply create it with some hashing command, like this:
❯ echo "my beautiful password" | sha256sum | cut -d" " -f1
The bash command will return something like this:
5c8ccefbcb9f9a0ef8a8d40225fa2aceff4d6601dfc43bbb55fb01ee33b9cf8a
Afterwards admin
user must be created with the register
command and the newly generated token:
❯ https://example.local:3000/register?user=admin&token=5c8ccefbcb9f9a0ef8a8d40225fa2aceff4d6601dfc43bbb55fb01ee33b9cf8a
⚠️ The first step must be the
admin
user creation. Any other command will fail with an empty Redis database.
Action: user-purge
If somehow a user password has been lost, the admin
can purge the user, allowing a new registration of the same username. For details, please see register
.
Example:
❯ https://example.local:3000/admin?action=user-purge&name=<username_with_forgotten_pass>&token=<admin_token>
Action: env-create
Environments must exist for hosts to use host locking. This command can be used by the admin
to create those dependency environments.
Example:
❯ https://example.local:3000/admin?action=env-create&name=<environment_name>&token=<admin_token>
Action: env-unlock
If some user locks an environment and it must be unlocked for any reason, the admin
can do that. Environments and hosts normally can be unlocked by their owners.
Example:
❯ https://example.local:3000/admin?action=env-unlock&name=<environment_name>&token=<admin_token>
Action: env-maintenance
There are occasional maintenance timeframes. The admin
can set it up. After the maintenance, it can be reverted by the admin
with the env-unlock
command.
Example:
❯ https://example.local:3000/admin?action=env-maintenance&name=<environment_name>&token=<admin_token>
Action: env-terminate
If an environment needs to be terminated for any reason, the admin
can do that with the env-terminate
action.
Example:
❯ https://example.local:3000/admin?action=env-terminate&name=<environment_name>&token=<admin_token>
Action: host-unlock
Host unlock is the same as env-unlock
but for hosts.
Example:
❯ https://example.local:3000/admin?action=host-unlock&name=<environment_name>&token=<admin_token>
Registering users
Except for the stats
command, all other command needs a responsible user, which must be registered beforehand. Every user registers their user, no admin
is needed for that.
❯ https://example.local:3000/register?user=<username>&token=<new_user_token>
Locking hosts and environments
To own a host or an environment, it must be locked.
⚠️ Please be aware of the
lastday
parameter which describes the last day of the lock of the given host or env. RedisDB will release the lock automaticallyon the next day.
Examples:
❯ https://example.local:3000/lock?type=host&name=<hostname>&user=<username>&token=<user_token>&lastday=<expire_day>
❯ https://example.local:3000/lock?type=env&name=<envname>&user=<username>&token=<user_token>&lastday=<expore_day>
Unlocking hosts and environments
Unlocking can be necessary sometimes before automatic unlocking happens, here is how to do that.
⚠️ Users cannot unlock envs or hosts owned by others. Only admin can do that.
Examples:
❯ https://example.local:3000/unlock?type=host&name=<hostname>&user=<username>&token=<user_token>
❯ https://example.local:3000/unlock?type=env&name=<envname>&user=<username>&token=<user_token>
Status queries
To view the locking status for all environments and hosts, no special user validation is needed.
At this point, the HTML web page and JSON data response are supported. Later YAML format will be added too.
Web HTML format (human readable)
❯ https://example.local:3000/status/web
JSON format
❯ https://example.local:3000/status/json
Guarantees, responsibility
Please see the license: https://github.com/drax2gma/nodelocker#Apache-2.0-1-ov-file