13. Digital Rebar Provision Operations

This section will attempt to describe common operations and actions that can be done. We will assume that drpcli is already somewhere in the path and have setup the environment variables to access Digital Rebar Provision. See, Digital Rebar Provision Command Line Interface (CLI).

Some of these operations are in the User Interface (UI), but not all. This will focus on CLI usage for now. See the User Interface (UI) section for UI usage.

Note

drpcli normally spits out JSON formatted objects or an array of objects. To help with some of the command line functions, we use the jq tool. This is available for both Linux and Darwin.

13.1. Preference Setting

Usually, it is necessary to get or set the preferences for the system.

# Show the current preference settings
drpcli prefs list

# Or get a specific one
drpcli prefs get unknownBootEnv

Set a preference

# Set a preference
drpcli prefs set unknownBootEnv discovery

# or chain multiples as pairs
drpcli prefs set unknownBootEnv discovery defaultBootEnv sledgehammer

The system does validate values to make sure they are sane, so watch for errors.

13.2. BootEnv Operations

13.2.1. Installing a “Canned” BootEnv

Manipulating BootEnv and Template are handled by their own commands. There are some additional helpers especially when following the layout of the initial Install.

To install a provided BootEnv, do the following from the install location.

cd assets
drpcli bootenvs install bootenvs/ubuntu-16.04.yml

This is a CLI helper that is not in the API that will read the provided YAML BootEnv file, upload the included or referenced Template files (from the templates peer directory), upload the BootEnv, and check for an existing ISO in the ISO repository. If an ISO is not present in the already uploaded list, it will check a local isos directory for the file. If that is not present and the BootEnv contains a URL for the ISO, the ISO will attempt to be downloaded to the local isos directory and then uploaded into Digital Rebar Provision. Once upload, the ISO is “exploded” for access by machines in the file server file system space.

13.2.2. Cloning a BootEnv

Sometimes there is a BootEnv but it is necessary to make changes. These can be handled by Template inclusion, but for now let’s just focus on basic “cut and paste” style editing.

drpcli bootenvs show ubuntu-16.04-install --format yaml > new-file.yaml
# Edit the file
#  change the Name field to something new. *MUST DO THIS*
#  change the OS->Name field to something new to avoid sharing an iso directory.
#  Edit other parameters as needed
drpcli bootenvs create - < new-file.yaml

This is a shallow clone. It will reuse the templates unless they are explicitly modified. It is possible to use the install command, but any new templates would need to be added to a templates directory in the current directory.

13.2.3. Creating a BootEnv

It might be necessary to create an empty BootEnv by doing the following:

drpcli bootenvs create emtpy_bootenv

This BootEnv will not be Available, but will allow for additional editing.

13.2.4. Editing a BootEnv

It might be necessary to edit a BootEnv. To do this, get the latest copy with the show command. Edit the file as needed. Then using the update command, put the value back. The –format=yaml is optional, but I find YAML easier to edit.

drpcli bootenvs show discovery --format=yaml > discovery.yaml
# Edit the discovery.yaml as needed
drpcli bootenvs update discovery - < discovery.yaml

13.3. Template Operations

13.3.1. Cloning a Template

It might be necessary to create a new template from an existing one. To do this, do the following:

drpcli templates show net_seed.tmpl | jq -r .Contents > new.tmpl
# Edit the new.tmpl to be what is required
drpcli templates upload new.tmpl as new_template

In this case, we are using jq to help us out. jq is a JSON processing command line filter. JSON can be used to retrieve the required data. In this case, we are wanting the Contents of the template. We save that to file, edit it, and upload it as a new template, new_template.

It is possible to use the create subcommand of template, but often times upload is easier.

Note

Remember to add the new template to a BootEnv or another Template as an embedded template.

13.3.2. Updating a Template

It might be necessary to edit an existing template. To do this, do the following:

drpcli templates show net_seed.tmpl | jq -r .Contents > edit.tmpl
# Edit the edit.tmpl to be what is desired
drpcli templates upload edit.tmpl as net_seed.tmpl

We use jq to get a copy of the current template, edit it, and use the upload command to replace the template. If there already is a template present, then it can be replaced with the upload command.

13.4. Profile Operations

13.4.1. Creating a Profile

It might be necessary to create a Profile. An empty profile can be created by doing the following:

drpcli profiles create '{ "Name": "myprofile" }'

or

drpcli profiles create myprofile

The system will attempt to use any sent string as the Name of the profile.

Additionally, JSON can be provided to fill in some default values.

drpcli profiles create '{ "Name": "myprofile", "Params": { "string_param1": "string", "map_parm1": { "key1": "value", "key2": "value2" } } }'

13.4.2. Deleting a Profile

It might be necessary to delete a Profile. It is possible to use the destroy command in the profile CLI, but the Profile must not be in use. Use the following:

drpcli profiles destroy myprofile

13.4.3. Altering an Existing Profile (including global)

It might be necessary to update an existing Profile, including global. parameter values can be set by doing the following:

drpcli profiles set myprofile param crazycat to true
# These last two will show the value or the whole profile.
drpcli profiles get myprofile param crazycat
drpcli profiles show myprofile

Note

Setting a parameter’s value to null will clear it from the structure.

Alternatively, the update command can be used to send raw JSON similar to create.

drpcli profiles update myprofile '{ "Params": { "string_param1": "string", "map_parm1": { "key1": "value", "key2": "value2" }, "crazycat": null } }'

Update is an additive operation by default. So, to remove items, null must be passed as the value of the key to be removed.

13.5. Machine Operations

13.5.1. Creating a Machine

It might be necessary to create a Machine. Given the IP that the machine will boot as all that is required is to create the machine and assign a BootEnv. To do this, do the following:

drpcli machine create '{ "Name": "greg.rackn.com", "Address": "1.1.1.1" }'

This would create the Machine named greg.rackn.com with an expected IP Address of 1.1.1.1. dr-provision will create the machine, create a UUID for the node, and assign the BootEnv based upon the defaultBootEnv Prefs.

drpcli machine create '{ "Name": "greg.rackn.com", "Address": "1.1.1.1", "BootEnv": "ubuntu-16.04-install" }'

This would do the same thing as above, but would create the Machine with the ubuntu-16.04-install BootEnv.

Note

The BootEnv MUST exist or the create will fail.

To create an empty Machine, do the following:

drpcli machine create jill.rackn.com

This will create an empty Machine named jill.rackn.com.

Note

The defaultBootEnv BootEnv MUST exist or the create will fail.

13.5.2. Adding or Removing a Profile to a Machine

It might be necessary to add or remove a Profile to or from a Machine. To add a profile, do the following:

drpcli machines addprofile "dff3a693-76a7-49ce-baaa-773cbb6d5092" myprofile

To remove a profile, do the following:

drpcli machines removeprofile "dff3a693-76a7-49ce-baaa-773cbb6d5092" myprofile

The Machine update command can also be used to modify the list of Profile.

13.5.3. Changing BootEnv on a Machine

It might be necessary to change the BootEnv associated with a Machine. To do this, do the following:

drpcli machines bootenv drpcli "dff3a693-76a7-49ce-baaa-773cbb6d5092" mybootenv

Note

The BootEnv MUST exists or the command will fail.

13.6. DHCP Operations

13.6.1. Creating a Reservation

It might be necessary to create a Reservation. This would be to make sure that a specific MAC Address received a specific IP Address. Here is an example command.

drpcli reservations create '{ "Addr": "1.1.1.1", "Token": "08:00:27:33:77:de", "Strategy": "MAC" }'

Additionally, it is possible to add DHCP options or the Next Boot server.

drpcli reservations create '{ "Addr": "1.1.1.5", "Token": "08:01:27:33:77:de", "Strategy": "MAC", "NextServer": "1.1.1.2", "Options": [ { "Code": 44, "Value": "1.1.1.1" } ] }'

Remember to add an option 1 (netmask) if a subnet is not being used to fill the default options.

13.7. User Operations

13.7.1. Creating a User

It might be necessary to create a User. By default, the user will be created without a valid password. The user will only be able to access the system through granted tokens.

To create a user, do the following:

drpcli users create fred

Note

This User will NOT be able to access the system without additional admin action.

13.7.2. Granting a User Token

Sometimes as an administrator, it may be necessary to grant a limited use and scope access token to a user. To grant a token, do the following:

drpcli users token fred

This will create a token that is valid for 1 hour and can do anything. Additionally, the CLI can take additional parameters that alter the token’s scope (model), actions, and key.

drpcli users token fred ttl 600 scope users action password specific fred

This will create a token that is valid for 10 minutes and can only execute the password API call on the User object named fred.

To use the token in with the CLI, use the -T option.

drpcli -T <token> bootenvs list

13.7.3. Deleting a User

It might be necessary to remove a reset from the system. To remove a user, do the following:

drpcli users destroy fred

13.7.4. Revoking a User’s Password

To clear the password from a User, do the following:

drpcli users update fred '{ "PasswordHash": "12" }'

This basically creates an invalid hash which matches no passwords. Issued tokens will still continue to function until their times expire.

13.7.5. Secure User Creation Pattern

A secure pattern would be the following:

  • Admin creates a new account

    drpcli users create fred
    
  • Admin creates a token for that account that only can set the password and sends that token to new user.

    drpcli users token fred scope users action password ttl 3600
    
  • New user uses token to set their password

    drpcli -T <token> users password fred mypassword