Service bootstrap

“Bootstrapping” means creating a superadmin account and password, which acts as the master secret that protects the RADKit Service database. This is an important step that must be performed as soon as possible after installation.

This page describes various ways that you can bootstrap your RADKit Service – locally or remotely; interactively or not; using a graphical or text-based interface. If this looks overwhelming, check out the Quick start guide for a simple setup procedure.

Danger

The superadmin password will be used to protect secrets such as private keys and device credentials; if you lose it, all secrets will be lost, so choose it carefully and store a copy in a secure location like a password vault. It can be changed later as needed.

Using the Service GUI

Note

Due to a library compatibility problem, the “RADKit Service GUI” application is no longer supported on Linux until further notice. The Service WebUI is not affected.

For this method, RADKit Service must be either STOPPED, or running as a Windows service.

Start the RADKit Service GUI (either through its application shortcut, or by running radkit-service-gui at the prompt if your PATH is correctly set). Once the status changes to “not yet bootstrapped”, press “Configure RADKit”.

This will open a web browser and take you to the Service WebUI where you can create the superadmin account (see warning and screenshot in the next section).

Using the Service WebUI

For this method, RADKit Service must be RUNNING.

Point your browser to https://localhost:8081 (this is the URL to use if RADKit Service is running locally with default settings; if RADKit Service is running remotely and/or with a custom TCP port number, adjust the URL accordingly).

Warning

Since RADKit Service starts up with a self-signed TLS certificate, you may get a warning from your browser that the certificate is invalid. Please take extra care in validating the address and port number that you are accessing before you enter any secrets.

Using RADKit Control

For this method, RADKit Service must be RUNNING.

Run the command radkit-control system bootstrap in a terminal (your PATH must be correctly set). RADKit Control will connect to the running RADKit Service’s API and bootstrap it remotely. It will prompt the user twice for the superadmin password; note that the password must comply with the Service password policy.

$ radkit-control system bootstrap
Provide a password for superadmin:
Confirm:
{
    "success": true,
    ...
}

Warning

If instead of "success": true, you get "success": false and a message that says "No session available for request", then your RADKit Service is already bootstrapped.

By default, RADKit Control will connect to the local host on the default Service port. This can be changed through Control settings via CLI parameters, environment variables, or TOML settings (for more information, see Settings management). For example, if your RADKit Service is running locally on the non-default port 8082:

% radkit-control -s control.service_url https://localhost:8082/api/v1 system bootstrap

It is also possible to perform a non-interactive bootstrap by passing the superadmin password through one of the control.admin_password setting variations. The recommended way for automation is to use control.admin_password_file and ensure that access to that file is strictly restricted:

$ touch ~/secrets/superadmin
$ chmod go-rwx ~/secrets/superadmin
$ vim ~/secrets/superadmin
$ export RADKIT_CONTROL_ADMIN_PASSWORD_FILE=~/secrets/superadmin
$ radkit-control system bootstrap
{
    "success": true,
    ...
}

If you are getting the following error, then the Service is already bootstrapped:

{
    "success": false,
    "message": "No session available for request",
    "detail": null
}

Using the Service CLI

Warning

This method is now deprecated in favor of RADKit Control and should only be used with guidance from Cisco TAC or RADKit support.

For this method, RADKit Service must be STOPPED.

Invoke the bootstrap subcommand of the RADKit Service CLI (your PATH must be correctly set). If you don’t specify the --radkit-directory option before the bootstrap keyword, the current user’s $HOME/.radkit directory will be used. This will not have the desired effect if you are running RADKit Service as a Windows or systemd service.

By default the Service CLI will prompt the user twice for the superadmin password. Note that the password must comply with the Service password policy.

% radkit-service bootstrap
07:24:51.009Z INFO  | internal | Logging configured [root_level=ERROR level=INFO con_level=TRACE con_json=False file_level=TRACE file_json=False file_name='/home/user/.radkit/logs/service/service.log' file_rotate=True with_rate_limiting=True]
07:24:51.009Z INFO  | internal | RADKit Service [version='1.7.0b7+17.gb5d7b7d3a']
Set up the superadmin user. You'll be asked to provide a superadmin password.
Keep this password securely stored, as it will be impossible to recover it!
Superadmin password (for new setup): *********
Confirm: *********
07:24:57.860Z INFO  | internal | Creating new database file. [path=PosixPath('/home/user/.radkit/service/service-db.json.encrypted')]
07:24:57.861Z INFO  | internal | Storing DB encryption key in credentials backend. [path=PosixPath('/home/user/.radkit/service/service-db.json.encrypted')]
07:24:57.948Z INFO  | internal | Opening database. [path=PosixPath('/home/user/.radkit/service/service-db.json.encrypted')]
07:24:57.949Z INFO  | internal | Ensuring backup directory [backup_dir_path='/home/user/.radkit/service/backups/20240906-092457_1.7.0b7+17.gb5d7b7d3a']
07:24:57.949Z INFO  | internal | Backing up keys and certs files...
...
07:24:57.963Z INFO  | internal | Creating administrator [admin_name='superadmin']
07:24:57.965Z INFO  | internal | Database closed. [path=PosixPath('/home/user/.radkit/service/service-db.json.encrypted')]

Bootstrapping is complete. The next step is to enroll with the RADKit Certificate Authority.
You can now start the Service with 'radkit-service run' and log on to the WebUI as 'superadmin'.
Alternatively, you can enroll through the CLI (see documentation for details).

It is also possible to perform a non-interactive bootstrap by passing the superadmin password through one of the means described in Storing the superadmin password. If a value for the password is available during the bootstrap phase, it will be used and the user will not be prompted.