24.15. drp-community-content - Community Core

The following documentation is for Community Core (drp-community-content) content package at version v4.6.0-alpha00.289+g5c46fa5acc1eb1e07540a21a03a3035140571967.

24.15.1. Community Content

The drp-community-content is a required initial content package for Digital Rebar Provision if you plan to use any of the digital rebar content.

This contains the basic building blocks of all the rest of the system. From basic bootenvs, stages, and workflows to templates and tasks, this content pack starts the whole process.

24.15.2. Object Specific Documentation

24.15.2.1. tasks

The content package provides the following tasks.

24.15.2.1.1. network-manage-routes

Configure the system to add or remove additional Route statements provided in the network-data Param. The network-manage-routes-command should be set to one of add or delete to define which action to take.

If a route exists already, and the add action has been set (the default), then the route will first be removed, then re-added.

In addition to network-data, the network-data-tag must be specified to select the correct set of configuration data references found in network-data.

This task is designed to work on Linux (via ip2 suite of commands), ESXi, and MacOS X (Darwin). As such, it uses sh since VMware vSphere ESXi appliances do not have a proper BASH shell (they use a modified busybox shell).

24.15.2.1.2. os-identity

A task to set the os-identity Param to a known value for future tasks to utilize.

24.15.2.1.3. set-machine-name-from-hostname

This Task sets the Machine Object .Macine.Name value to the current Machine objects Parameter named hostname. This is often used in discovery stages, where the Classify functions may set a Machines Param hostname to a value based on the classify actions.

This Task should be run after any Classify action Stages which perform add_parameter hostname BOB actions - or similar Tasks that set the Machine objects hostname Param.

24.15.2.1.4. set-machine-ip-in-joinup

/ Alternative to set-machine-ip-in-sledgehammer. Used to read an existing IP address and assign it to the Machine This is needed when using the Join-Up process in clouds where no DHCP is used and machines are assigned fixed addresses. Needed in >v4.3 because IP setting was removed from join-up.sh

24.15.2.1.5. ssh-access

This task populates the root’s authorized keys file and makes sure that the sshd config for PermitRootLogin is populated.

Runs as part of a shell script for kickstart or net-post-install.

If the access-ssh-template is specified, that template is used to replace the existing sshd config file.

Otherwise, the task will use the access-keys, access-keys-shared, and access-keys-global parameters to define keys to inject into the authorized_keys file for root.

The access-ssh-root-mode and access-ssh-parameters will alter the sshd config file. The access-ssh-parameters parameter is a general key/value map to replace config sections.

Optional Parameters: * access-keys * access-keys-shared * access-keys-global * access-ssh-root-mode * access-ssh-parameters * access-ssh-template

Parameter YAML format:

access-keys:
  greg:  ssh-rsa key
  greg2:  ssh-rsa key
access-ssh-root-mode: "without-password|yes|no|forced-commands-only"

Defaults: * access-keys - empty * access-ssh-root-mode - defaults to “without-password” if unspecified

24.15.2.1.6. gohai

Sets Param: gohai-inventory

Collect inventory from machines using drpcli gohai command and store the result in the gohai-inventory Param on the machine.

If you want to disable this behavior, set the gohai/skip Param to true.

Hint: this can be A LOT of data added to the machine param! You may want to use ?slim in the API to skip returning it on list requests.

24.15.2.1.7. bootstrap-discovery-iso

This tasks downloads and uploads to DRP the sledgehammer isos.

24.15.2.1.8. configure-network

Configures the network during OS install. This uses the net/interface-topology and net/interface-config params to write out the network configuration that should be used once the system reboots after the install finishes

24.15.2.1.9. empty-gpt-tables

For every disk found in the system, write an empty GPT table on the disk. This typically should follow the prep-install Stage which wipes the disks clean.

Useful for disks destined for VMware vSphere VSAN or other storage solutions that require starting with a clean disk with an empty GPT table to use the disk.

24.15.2.1.10. reserve-dhcp-address

Generate a reservation for the current DHCP address assignment.

This is assumed to run in sledgehammer after the set-machine-ip-in-sledgehammer.

24.15.2.1.11. always-pxe-in-uefi-first

Certian Linux distributions reorder the UEFI boot options to always locally boot from their install first, which is not generally what dr-provision wants, as it makes regaining control of the machine by PXE booting it to Sledgehammer harder. This task rewrites the UEFI boot order to have whatever device we booted from be the first.

24.15.2.1.12. bootstrap-ssh

This creates an ssh key pair if one doesn’t exist. It then adds the public key to the access-keys parameters. if the access-keys parameter already exists, the task does nothing.

Note: will use existing id_rsa.pub if provided.

24.15.2.1.13. set-machine-ip-in-sledgehammer

/ This logic replicates what our DHCP server does behind the scenes to make sure that machines do not have conflicting addresses. This works because and Address of 0.0.0.0 is unset. Needed in >v4.3 because IP setting was removed from join-up.sh

24.15.2.1.14. bootstrap-prefs

A task to set the default preferences for default install.

NOTE: Will NOT change prefs if defaultWorkflow is set.

Also sets the Icon for the machine.

24.15.2.1.15. enforce-sledgehammer

Sets Param: gohai-inventory

Collect inventory from machines using drpcli gohai command and store the result in the gohai-inventory Param on the machine.

If you want to disable this behavior, set the gohai/skip Param to true.

Hint: this can be A LOT of data added to the machine param! You may want to use ?slim in the API to skip returning it on list requests.

24.15.2.1.16. lock-machine

Sets Field: Lock

Lock the machine so users can not alter the machine. Current tasks and machine actions will continue to run.

24.15.2.1.17. sledgehammer-set-working-python

Starting with the CentOS 8 version of Sledgehammer, there are two versions of Grub available – python2 (2.7), and python3 (3.6).

This task, in conjunction with the spedgehammer/working-python parameter, allows you to set which python is loaded when you use /usr/bin/python

24.15.2.2. workflows

The content package provides the following workflows.

24.15.2.2.1. discover-base

This workflow is the most basic provisioning process for DRP.

It starts the discover Stage which sets up the sledgehammer BootEnv. After Sledgehammer starts, it leaves the DRP runner in a waiting state so that DRP will automatically detect and start a new workflow if the Machine.Workflow is updated.

NOTE: To enable, upload Sledgehammer as per the sledgehammer BootEnv

24.15.2.2.2. bootstrap-base

Bootstrap Digital Rebar server for minimal operation.

REQUIRES that the Endpoint Agent has been enabled.

  • Make sure Sledgehammer bootenvs are loaded for operation.
  • Set the basic default preferences.
  • Setup an ssh key pair and install it to the global profile.
  • Locks the endpoint to prevent accidential operations

This is designed to be extended or replaced with a site specific bootstrap-base that uses the base tasks but performs additional bootstrapping.

24.15.2.2.3. debian-base

This workflow includes the DRP Runner in Ubuntu provisioning process for DRP.

After the install completes, the workflow installs the runner in a waiting state so that DRP will automatically detect and start a new workflow if the Machine.Workflow is updated.

Note

To enable, upload the firmware-10 ISO as per the debian-10 BootEnv

24.15.2.3. bootenvs

The content package provides the following bootenvs.

24.15.2.3.1. custom-ipxe

This bootenv allows you to specify a custom iPXE config file to boot the system via. You’re PXE kernel file should be named “ipxe.pxe”.

24.15.2.3.2. debian-8-install

This BootEnv installs Debian 8 via the “mini” ISO file.

24.15.2.3.3. sledgehammer

The Sledgehammer BootEnv is used in conjunction with Discovery to boot a machine in to an in-memory (RAM only) operating system. The Machine will be enrolled in the DRP Endpoint via Sledgehammer.

Many maintenance and hardware related workflows require to be run from the Sledgehammer BootEnv.

24.15.2.3.4. ubuntu-18.04-arm64-hwe-install

Installs Ubuntu Bionic Beaver (18.04) HWE version for ARM64 architecture.

NOTE - Default Ubuntu ISOs will attempt to check internet repositories, this can cause problems during provisioning if your environment does not have outbound access. Workaround this by defining Options 3 (Gateway) and 6 (DNS) for your Subnet settings. See https://provision.readthedocs.io/en/latest/doc/kb/kb-00033.html

24.15.2.3.5. debian-9-install

This BootEnv installs Debian 9 via the “mini” ISO file.

24.15.2.3.6. fedora-31-install

This BootEnv installs the Fedora 31 Minimal server operating system. x86_64 is supported.

24.15.2.3.7. ubuntu-20.04.1-install

Installs Ubuntu Focal Fossa (20.04.1) LTS version. This BootEnv will install the General Available (GA) kernel. If you wish to install the HWE (Hardware Enablement) version, please use the Stage “ubuntu-20.04-hwe-install”. Both amd64 and arm64 architectures are supported.

NOTE - Default Ubuntu ISOs will attempt to check internet repositories, this can cause problems during provisioning if your environment does not have outbound access. Workaround this by defining Options 3 (Gateway) and 6 (DNS) for your Subnet settings. See https://provision.readthedocs.io/en/latest/doc/kb/kb-00033.html

part-scheme can be used to inject a storage section.

The template would be named “part-scheme-<Value of part-scheme>”.

The format should be:

Note Indentation matters with the extra two spaces.

  storage:
    swap:
      size: 0
    layout:
      name: direct
      match:
        ssd: yes

24.15.2.3.8. centos-7.8.2003-install

This BootEnv installs the CentOS 7 Minimal operating system. Both x86_64 and aarch64 architectures are supported.

24.15.2.3.9. centos-8-install

This BootEnv installs the CentOS 8 Minimal operating system. Both x86_64 and aarch64 architectures are supported.

ISOs can be downloaded from:

24.15.2.3.10. centos-8.1.1911-install

This BootEnv installs the CentOS 8 Minimal operating system. Both x86_64 and aarch64 architectures are supported.

24.15.2.3.11. debian-10-install

This BootEnv installs Debian 10 via netinst ISO file.

24.15.2.3.12. fedora-33-install

This BootEnv installs the Fedora 33 Minimal server operating system. x86_64 is supported.

ISOs can be downloaded from the Fedora download website, at:

24.15.2.3.13. ubuntu-16.04-install

NOTE: Default Ubuntu ISOs will attempt to check internet repositories, this can cause problems during provisioning if your environment does not have outbound access. Workaround this by defining Options 3 (Gateway) and 6 (DNS) for your machines defined Subnet. See https://provision.readthedocs.io/en/latest/doc/kb/kb-00033.html

24.15.2.3.14. centos-7.6.1810-install

This BootEnv installs the CentOS 7 Minimal operating system. Both x86_64 and aarch64 architectures are supported.

24.15.2.3.15. centos-7.9.2009-install

This BootEnv installs the CentOS 7 Minimal operating system. Both x86_64 and aarch64 architectures are supported.

24.15.2.3.16. centos-8.3.2011-install

This BootEnv installs the CentOS 8.3.2011 DVD operating system. Both x86_64 and aarch64 architectures are supported.

ISOs can be downloaded from:

24.15.2.3.17. discovery

Normal option of this bootenv is to provision physical services using sledgehammer.

To join EXISTING machines or CLOUD machines into DRP, you can use run join-up.sh. Add the following line to the machines initialization script:

#!/bin/bash
curl -fsSL [internal ip]:8091/machines/join-up.sh | sudo bash --

To join EXISTING machines or CLOUD machines running ESXi into DRP, you can use esxi-join-up.py. To run this you will first need to install 2 packages RackN provides in vib or component format that have been signed by VMware. You will need the DRP-Firewall-Rule and the DRP-Agent packages. These packages are available on your local DRP endpoint. Before those packages can be installed a partial configuration file will need to be placed on the HostSystem. These steps will need to be done in order. The following commands can be run from the HostSystem you plan to join to DRP.

RKN_DIR=$(localcli --formatter json storage filesystem list|python -c "import sys,json;x=json.load(sys.stdin);y=[i for i in x if i['Type']=='VFFS' or 'vmfs' in i['Type'].lower()];print(y[0]['Mount Point'])")/rackn
mkdir -p $RKN_DIR
cd $RKN_DIR
# For 6.x
wget -O DRP-Agent.zip [internal ip]:8091/files/plugin_providers/vmware/6.x/DRP-Agent-signed.zip
wget -O DRP-Firewall-Rule.zip [internal ip]:8091/files/plugin_providers/vmware/6.x/RKN-DRPY-FW-RULE_1.0-0.0.0003-offline_bundle-16370411.zip
# For 7.x
wget -O DRP-Agent.vib [internal ip]:8091/files/plugin_providers/vmware/7.x/DRP-Agent-signed.zip
wget -O DRP-Firewall-Rule.zip [internal ip]:8091/files/plugin_providers/vmware/7.x/RKN-DRPY-FW-RULE_1.0-0.0.0003_16333171.zip

wget [internal ip]:8091/files/plugin_providers/vmware/drpy.conf
localcli software vib install -d ./DRP-Firewall-Rule.zip
localcli software vib install -d ./DRP-Agent.zip

Next you can download the join up script, and then run it:

wget [internal ip]:8091/machines/esxi-join-up.py
python esxi-join-up.py

When this process completes you will get output letting you know the machine was added to inventory.

24.15.2.3.18. ubuntu-20.04-install

Installs Ubuntu Focal Fossa (20.04) LTS version. This BootEnv will install the General Available (GA) kernel. If you wish to install the HWE (Hardware Enablement) version, please use the Stage “ubuntu-20.04-hwe-install”. Both amd64 and arm64 architectures are supported.

NOTE - Default Ubuntu ISOs will attempt to check internet repositories, this can cause problems during provisioning if your environment does not have outbound access. Workaround this by defining Options 3 (Gateway) and 6 (DNS) for your Subnet settings. See https://provision.readthedocs.io/en/latest/doc/kb/kb-00033.html

part-scheme can be used to inject a storage section.

The template would be named “part-scheme-<Value of part-scheme>”.

The format should be:

Note Indentation matters with the extra two spaces.

  storage:
    swap:
      size: 0
    layout:
      name: direct
      match:
        ssd: yes

24.15.2.3.19. ubuntu-20.04.0-install

Installs Ubuntu Focal Fossa (20.04.0) LTS version. This BootEnv will install the General Available (GA) kernel. If you wish to install the HWE (Hardware Enablement) version, please use the Stage “ubuntu-20.04-hwe-install”. Both amd64 and arm64 architectures are supported.

NOTE - Default Ubuntu ISOs will attempt to check internet repositories, this can cause problems during provisioning if your environment does not have outbound access. Workaround this by defining Options 3 (Gateway) and 6 (DNS) for your Subnet settings. See https://provision.readthedocs.io/en/latest/doc/kb/kb-00033.html

part-scheme can be used to inject a storage section.

The template would be named “part-scheme-<Value of part-scheme>”.

The format should be:

Note Indentation matters with the extra two spaces.

  storage:
    swap:
      size: 0
    layout:
      name: direct
      match:
        ssd: yes

24.15.2.3.20. centos-7-install

This BootEnv installs the CentOS 7 Minimal operating system. Both x86_64 and aarch64 architectures are supported.

24.15.2.3.21. centos-7.7.1908-install

This BootEnv installs the CentOS 7 Minimal operating system. Both x86_64 and aarch64 architectures are supported.

24.15.2.3.22. centos-8.2.2004-install

This BootEnv installs the CentOS 8.2.2004 Minimal operating system. Both x86_64 and aarch64 architectures are supported.

24.15.2.3.23. ubuntu-18.04-install

Installs Ubuntu Bionic Beaver (18.04) LTS version. This BootEnv will install the General Available (GA) kernel. If you wish to install the HWE (Hardware Enablement) version, please use the Stage “ubuntu-18.04-hwe-install”.

Both amd64 and arm64 architectures are supported.

NOTE - Default Ubuntu ISOs will attempt to check internet repositories, this can cause problems during provisioning if your environment does not have outbound access. Workaround this by defining Options 3 (Gateway) and 6 (DNS) for your Subnet settings. See https://provision.readthedocs.io/en/latest/doc/kb/kb-00033.html

24.15.2.4. params

The content package provides the following params.

24.15.2.4.1. access-keys

This map is used to put ssh public keys in place for the root user.

For shared and global keys to include in addition, use access-keys-shared and access-keys-global

The key of the map is a arbritary name and the value is the ssh public key for that name.

Parameter YAML format:

access-keys:
  greg:  ssh-rsa key
  greg2:  ssh-rsa key

24.15.2.4.2. detected-bios-mode

The BIOS mode that the machine was last detected to be operating in. This can be either unknown, legacy-bios, or uefi.

Other BIOS modes will be added on an as-needed basis, and will require a corresponding update to Sledgehammer to set.

24.15.2.4.3. hostname

Allow setting a hostname. In some use cases, the DHCP provided provisioning name (the templatized .Machine.Name) may not be correct for final production personality of the Machine.

This value could be set as a Param/Profile on the machine either by a human operator, or subsequent integration with IPAM, SoR, or other services.

This is used in the VMware ESXi provisioning kickstarts.

To set the hostname of most Linux hosts update the value of .Machine.Name.

24.15.2.4.4. kernel-options

This string defines any extra options that the operator may need to pass to the Kernel during the PXE boot process. The string you enter will be directly passed, so if your distro requires comma, or space seperation of options define them accordingly.

e.g. “acpi=off”

These options will be passed before the argument processing is disabled (eg prior to “–”).

The “kernel-console” option can be used to specify the Console to log to (for example serial port), which is placed after the argument processing (eg after the “–”).

24.15.2.4.5. local-repo

DEPRECATED: Do not use.

Boolean value that tells the install steps to only use the local exploded iso on the DRP server as the only installation repo.

24.15.2.4.6. security/debug-block

Since rs-debug-enable may expose sensitive information, setting ANY value in this Param will block places where rs-debug-enable can be set in common libraries.

If true, it will
  1. set RS_DEBUG_ENABLE=false in setup.tmpl
  2. attempt to set rs-debug-enable:false on the machine if it was set true

If false, it will not set RS_DEBUG_ENABLE at all or change machine values

Design note: use of this variable is exists or not exists because we do not want potential users to be able to override a true value with a false value anywhere in the resolution chain.

24.15.2.4.7. access-ssh-parameters

This map defines a set of sshd_config file directives to replace in the current configuraiton file.

This format is:

Ciphers: aes256-ctr,aes192-ctr,aes128-ctr

This could be used to inject ciphers or mac lists.

24.15.2.4.8. access-ssh-template

This string the template name to use for the sshd_config file.

24.15.2.4.9. custom-ipxe

You can use this whenever you need a custom iPXE boot action, such as booting from a remote URL, booting to an iPXE prompt for troubleshooting, or simply playing around with different ipxe tools. This param defaults to launching an iPXE shell.

24.15.2.4.10. drp-agent/auto-update

When drpcli is starting up in agent mode, it has the capability to check in with the provisioner to see if the binary the provisioner os providing is different than the one on the local machine. If that is the case, then the agent will download the current version and use that, assuming that dr-provision has the agent-auto-update feature.

This functionality does not work on Windows due to not being able to remove running binaries. For now.

24.15.2.4.11. provisioner-default-password-hash

This specifies the password hash to use for the install process. This is the root password on CentOS-based installs, the default user on the Debian-based installs, and the root password for ESXi. Any other system that utilizes a SHA512 type hashed password can use this.

To generate a hash, use the following command:

# where "PASSWORD" is the new password to generate the hash for
python3 -c "import crypt; print(crypt.crypt(\"PASSWORD\", crypt.mksalt(crypt.METHOD_SHA512)))"

This will generate a sha512 hash which should work on both operating system types.

24.15.2.4.12. runner-tmpdir

Normally, when the machine agent runs tasks, it uses a hierarchy of scratch directories underneath /tmp to hold temporary running data, such as job logs, generated scripts, etc. This param allows you to override that default location on a machine-by-machine basis. On Unix systems, it does this by setting the TMPDIR environment variable to the value if this parameter when the agent start up. On Windows, it does so by setting the TMP environment variable instead. If this parameter is left unset, then the machine agent will use whatever the default values for the system are. This setting does not impact the ESXi agent (drpy)

24.15.2.4.13. start-over

Allows the operator to control if booting into sledgehammer should reset the task list on boot up. This allows things like bios update scripts to set the start-over flag to false and issue a reboot command and start over either at the current task or the next one.

24.15.2.4.14. kexec-ok

Allows the machine agent to call kexec to switch boot environments as long as the machine is currently running Linux, and the new environment has a template named ‘kexec’ that contains the kernel, initrds, and command line to use. This can be used to speed up deployments of systems that support kexec.

Note

Not all Linux kernels/distros ship with kexec support enabled. Check your distro for compatibility.

24.15.2.4.15. linux/install-bootenv-map

This map defines the mapping of linux/install-bootenv to a bootenv.

To choose a specific bootenv, use linux/install-bootenv-override.

24.15.2.4.16. machine-plugin

The plugin that should manage this machine.

24.15.2.4.17. network-data

This is a named set of key/value pairs. All data elements are strings.

This allows for the create of a named network with additional information about the network. Known supported keys within a network are:

  • name = the name of the network again (same as key)
  • dhcp = yes/no/true/false as a string. Remember to quote true or false.
  • vlan = VLAN ID number - Remember to quote numbers.
  • mtu = MTU for this network - Remember to quote numbers.
  • gateway = IPv4 Gateway address
  • netmask = IPv4 Netmaks
  • address = IPv4 Address - In some cases, this will NOT be required. DNS lookups…
  • inteface = a comma separated list of interfaces to used e.g. eth0,enp0s3 - if needed.
  • routes = a list of route objects
  • dns-servers = a list of dns-servers (though generally this is specified with the dns-servers parameter)

Leave the element out if not needed.

The all network can be used to define things that should apply to all networks. This is meant for dns-servers and routes currently.

For example:

all: # Special non-network to hold global-level things of routes and dns-servers
  routes:
  - network: 20.20.20.0
    gateway: 192.168.2.1
    netmask: 255.255.255.0
    interface: eth1
  dns-servers:
  - 8.8.8.8
  - 8.8.4.4
prov:
  name: prov
  dhcp: yes
  routes:
  - network: 10.10.10.0
    gateway: 192.168.1.1
    netmask: 255.255.255.0
    interface: eth0
prod:
  name: prod
  dhcp: no
  gateway: 10.2.3.1
  netmask: 255.255.255.0
  address: 10.2.3.15
stor:
  name: stor
  dhcp: no
  gateway: 10.3.3.1
  netmask: 255.255.255.0
  address: 10.3.3.15
  vlan: "2335"
  interface: "eth0,enp0s3"

24.15.2.4.18. network-data-output-type

The template network-data-parser.tmpl parses the network-data structure in a consistent manner and set of rules. To reuse the parsing rules, include the template in to other templates. Since golang templating can’t pass variables from an included template in to the scope of the operating template, we must rely on the scripted language Varaible definitions.

Setting this Param to one of the supported types, will tell the network-data-parser.tmpl to generate the correct Variable references for the targeted scripting language. Supported scripted languages are:

  • shell = Shell (BASH, SH, ZSH, BusyBox, ASH, ESXi Shell, etc)
  • powershell = PowerShell
  • python = Python (2 and 3 compatible)

If the shell environment type does not support the declare function, it is assumed that Arrays are not supported either. In this case, the Associative Array and related debug (if requested) statements will not be generated in the template. This is necessary to support environments like VMware ESXi BusyBox/ASH shells.

The default value shell (BASH, SH, BusyBox, ASH, etc).

24.15.2.4.19. provisioner-network-config

Used in the RHEL and possibly other BootEnvs to configure the systems network during installation. The default mode is to use DHCP. If this Param has a value set, then all valid option arguments must be specified.

RHEL 8 example to specify a static network configuration would set this Param to the volues as follows:

# RHEL 8 specific configuration for static network config during kickstart install
network --bootproto=static --ip=10.0.2.15 --netmask=255.255.255.0 --gateway=10.0.2.254 --nameserver=192.168.2.1,192.168.3.1

24.15.2.4.20. gohai/skip

Allows machines to stop using the discover-nogohai stage. When true, the gohai part of the discovery stage will be skipped

24.15.2.4.21. operating-system-disk

Defines the disk the installer should use for OS installation. The usage of this parameter inside a template should add a /dev/ if required. The value should just be the disk simple name.

e.g. sda

24.15.2.4.22. machine-meta/icon

The icon for machine’s icon

24.15.2.4.23. no-proxy

This is an array of locations that are exempt from the Proxy configured via the proxy-servers parameter.

24.15.2.4.24. ux-air-gap

Boolean value that tells the UX to not contact the SaaS because it is not reachable. This should only be set in the global profile.

See: Air Gap Install Instructions. For setup instructions.

This defaults to false.

24.15.2.4.25. package-repositories

This provides a list of repositories to install packages from. It includes dedicated OS installation repositories and more general ones.

An example:

- tag: "centos-7-install" # Every repository needs a unique tag.
  # A repository can be used by multiple operating systems.
  # The usual example of this is the EPEL repository, which
  # can be used by all of the RHEL variants of a given generation.
  os:
    - "centos-7"
  # We also need to know what system architecture this repo is for.
  # If this repo is valid for all arches (like a Debian or Ubuntu
  # mirror), this can be set to "any", although it cannot be
  # an installSource if that is the case
  arch: x86_64
  # If installSource is true, then the URL points directly
  # to the location we should use for all OS install purposes
  # save for fetching kernel/initrd pairs from (for now, we will
  # still assume that they will live on the DRP server).
  # When installSounrce is true, the os field must contain a single
  # entry that is an exact match for the bootenv's OS.Name field.
  installSource: true
  # For redhat-ish distros when installSource is true,
  # this URL must contain distro, component, and arch components,
  # and as such they do not need to be further specified.
  url: "http://mirrors.kernel.org/centos/7/os/x86_64"
- tag: "centos-7-everything"
  # Since installSource is not true here,
  # we can define several package sources at once by
  # providing a distribution and a components section,
  # and having the URL point at the top-level directory
  # where everything is housed.
  # DRP knows how to expand repo definitions for CentOS and
  # ScientificLinux provided that they follow the standard
  # mirror directory layout for each distro.
  os:
    - centos-7
  arch: x86_64
  url: "http://mirrors.kernel.org/centos"
  distribution: "7"
  components:
    - atomic
    - centosplus
    - cloud
    - configmanagement
    - cr
    - dotnet
    - extras
    - fasttrack
    - opstools
    - os
    - paas
    - rt
    - sclo
    - storage
    - updates
- tag: "debian-9-install"
  os:
    - "debian-9"
  arch: amd64
  installSource: true
  # Debian URLs always follow the same rules, no matter
  # whether the OS install flag is set.  As such,
  # you must always also specify the distribution and
  # at least the main component, although you can also
  # specify other components.
  url: "http://mirrors.kernel.org/debian"
  distribution: stretch
  components:
    - main
    - contrib
    - non-free
- tag: "debian-9-backports"
  os:
    - "debian-9"
  arch: any
  url: "http://mirrors.kernel.org/debian"
  distribution: stretch-updates
  components:
    - main
    - contrib
    - non-free
- tag: "debian-9-security"
  os:
    - "debian-9"
  arch: any
  url: "http://security.debian.org/debian-security/"
  securitySource: true
  distribution: stretch/updates
  components:
    - contrib
    - main
    - non-free

24.15.2.4.26. provisioner-default-uid

Used in the Debian/Ubuntu installers to specify the uid of the default user.

The value is a string for of the integer value.

24.15.2.4.27. reserve-dhcp-address

Boolean value that enables sledgehammer task, reserve-dhcp-address, to record the current MAC to IP mapping as a reservation.

24.15.2.4.28. network-data-tag

This Param sets the named object tag which should be selected from the network-data Param structure. This defines which data structure will be used when appropriate tasks/templates are applying network configuration values.

Note

This Param structure will be replaced with a new tagging method defined in Universal Workflow.

24.15.2.4.29. sledgehammer/enforce

Boolean parameter indicating if the enforce-sledgehammer task should ensure that the system is running in sledgehammer.

Note

This setting does not force a machine to boot into sledgehammer.

24.15.2.4.30. access-ssh-root-mode

This string defines the login policy for the root user.

Possible values are:

  • without-password - default
  • yes
  • no
  • forced-commands-only

24.15.2.4.31. gohai-inventory

Gohai is the DRPCLI embedded JSON machine inventory format. This param storage the result of that command when run during discovery. It is used by a number of downstream stages and workflows, and other content packs.

This provides an untyped dictionary of values from Gohai.

NOTE: This is raw data. Other parameters are distilled from this.

24.15.2.4.32. kickstart-base-packages

This provides a list of packages to be installed during a CentOS, RHEL, Fedora, and compatible package based kickstar install. Here is an example of how to override the default packages used for CentOS

{"centos": ["@core", "openssh"]}

24.15.2.4.33. zero-hard-disks-for-os-install

By default, the erase disks for os install task tries to only erase any metadata on the disks that may confuse a next OS install, along with (optionally) attempting to discard all sectors on devices that support discard. If this is set to true, the task will also zero all sectors on any non-SSD drives.

24.15.2.4.34. extra-packages

This is an array of strings where each string is an additional package to install during the initial OS install.

24.15.2.4.35. net/interface-topology

This parameter defines what the local network interface topology on a machine should look like, as expressed in netplan format. https://netplan.io/reference defines how this param must be formatted, with a few key differences:

  • It only supports systemd-networkd and old-style Redhat network configurations as output formats. Debian style is a planned on, and NetworkManager style is a lower priority.
  • No support for configuring wireless interfaces or tunnel devices. Wireless support is omitted because this tool is mainly intended for servers and other devices that do not have wireless interfaces. Tunnel devices are omitted primarily due to developer bandwidth constraints.
  • No support for NIC renaming or MAC address reassignment. Support may be added at a later date.
  • Where ther netplan.io spec calls for glob expansion when matching names or device drivers, we also allow full regular expressions, as long as the match in question starts with ^.
  • No support for per-interface backend renderers. This just doesn’t seem like a good idea if you don’t care about dynamic interface reconfiguration.
  • Support for a few interesting generic interface match names in the netplan:
    • bootif is the interface the system last booted from, as recorded by the last-boot-macaddr Param.
    • onboard:1onboard:n The first through nth onboard nics. Whether a nic is onboard or not is determined by what udev thinks.
    • pci:1pci:n The first through nth nic in PCI expansion slots. These nics are always ordered by their PCI bus ordering, which can vary on a system by system basis.
    • usb:1usb:n The first through nth USB nics, also ordered by bus order. If you want to use one of these, make sure it stays plugged in to the same USB port.

This param primarily concerns itself with topology, not address management, which is handled by the net/interface-config param instead. As such, you should not include any addresses, routes, etc in this param. If you do, they will be overridden by matching fields for the matching interface IDs in the net/interface-config param. In netplan terminollogy, this param should contain a match stanza for each ID that requires it, along with any device-specific properties required for virtual devices ( vlan ID, bridge configuration settings, bond modes, etc).

The default for ths parameter is

network:
  version: 2

which leaves the network topology on the machine alone. A contrived example which bonds the onboard interfaces, bridges that bond with all the interfaces on expansion cards, and then creates a VLAN interface on top of that is as follows:

network:
  version: 2
  ethernets:
    onboards:
      match:
        name: '^onboard:.*'
    others:
      match:
        name: pci:*
  bonds:
    bond0:
      interfaces: [ onboards ]
      parameters:
        mode: '802.3ad'
  bridges:
    bridge0:
      interfaces: [ others, bond0 ]
  vlans:
    vlan0:
      id: 1000
      link: bridge0

Many other topologies are possible.

24.15.2.4.36. debian-buster-netcfg

It appears that in Debian 10 (Buster) - the use of any preseed directives to configure the network is hard coded to auto (DHCP) for single NIC hosts. Multiple NIC hosts will stop and ask the operator what NIC to use for installation.

This occurs regarldess of any preseed directives. The only apparent way to configure Debian 10 interfaces at installation are to pass the netcfg/… values on the Kernel command line.

This Param specifies that the network interface should be chosen automatically, regardless of the number of NICs in the system; with the default value set to:

  • netcfg/choose_interface=auto

If you replace auto with the name of the Network Interface, then the installer will use your explicitly set NIC.

For static IP assignment or, explicit NIC selection requirements, you will have to set this Param on the Machine object, the preseed directives are ignored.

An example to explicitly set a Static IP assignment for the installer is as follows:

  • netcfg/get_ipaddress=192.168.1.10 netcfg/get_netmask=255.255.255.0 netcfg/get_gateway=192.168.1.1 netcfg/get_nameservers=1.1.1.1,1.0.0.1 netcfg/choose_interface=eth0 netcfg/disable_autoconfig=true

24.15.2.4.37. kickstart/extra-ifs

Extra interfaces to configure during kickstart-based builds. This is only required if you are building an instance on a VM with nonstandard networking.

24.15.2.4.38. provisioner-default-user

Used in the Debian/Ubuntu installers to specify the username of the default user.

24.15.2.4.39. dns-search-domains

This is an array of strings where each string a domain to apply to the DNS search order list.

24.15.2.4.40. erase-hard-disk-set

This string defines the set of disks to erase. Space separated dev names.

e.g. “/dev/sda /dev/sdb”

24.15.2.4.41. last-boot-macaddr

Keeps track of the MAC address (in PXELINUX format) that the system most recently PXE booted from.

24.15.2.4.42. linux/install-bootenv

This string defines index in linux/install-bootenv-map to use for a bootenv. This is an enumerated value.

To choose a specific bootenv, use linux/install-bootenv-override.

The -latest means latest that DRP knows about.

24.15.2.4.43. ubuntu-hwe-kernel

Enables the HWE (Hardware Enablement) kernel for an Ubuntu system. The default kernel is the LTS GA (General Availability) kernel.

WARNING - The “net-seed.tmpl” uses the BootEnv “.Env.OS.Version” value in the preseed configuration, like

d-i  base-installer/kernel/altmeta   string hwe-18.04

You must verify that your Ubuntu version supports this syntax. For example, if you are booting “18.10”, insure that the following is valid (see the ISO “preseeds” directory for valid examples)

d-i  base-installer/kernel/altmeta   string hwe-18.10

24.15.2.4.44. access-keys-shared

Supplements local access-keys by adding group or shared keys (generally from a shared profile) Generally, access-keys are to be set for narrow use cases such as per machine.

This map is used to put ssh public keys in place for the root user.

The key of the map is a arbritary name and the value is the ssh public key for that name.

Parameter YAML format:

access-keys:
  greg:  ssh-rsa key
  greg2:  ssh-rsa key

24.15.2.4.45. dns-domain

This is used currently in the Ubuntu/Debian preseed file to specify the DNS Domain Name of the host.

This may be in flux.

24.15.2.4.46. dns-servers

This is an array of strings where each string an IP address of a DNS server.

24.15.2.4.47. kernel-console

This string defines the console tty string for the kernel boot string.

e.g. console=ttyS1,115200

24.15.2.4.48. local-security-repo

The string value is either a URL for Ubuntu systems or a host/path string for Debian systems. This will override the default security repos if specified.

24.15.2.4.49. network-manage-routes-command

The network-manage-routes task can either add or remove routes. This param defines which action for that Task to take. By default, the task will add routes, unless this param is set on the machine with the value remove.

The only allowed values are add or remove; with the default set to add.

24.15.2.4.50. provisioner-default-fullname

Used in the Debian/Ubuntu installers to specify the full name of the default user.

24.15.2.4.51. provisioner-selinux

Defines the SELinux mode to set on a system during installation.

Also see provisioner-selinux-type

24.15.2.4.52. proxy-servers

This is an array of URLs where each string is an HTTP proxy server to references.

The URLs can be names or IPs with ports and schemas.

24.15.2.4.53. machine-meta/color

The color of the machine’s icon

24.15.2.4.54. provisioner-access-key

Used in the RHEL and possibly other BootEnvs to configure/enable SSH server access during installtion. If this Param is set with a Publich SSH key half, then the system will attempt to configure it as an authorized_keys. In addition, the provisioner-default-username must be specfied.

24.15.2.4.55. timezone

The timezone for the system. There is not a default. This way if not set the systems will not alter the system state.

This is currently used by the IPMI subsystem, but may be used in future updates.

24.15.2.4.56. catalog_url

The URL that the UX should use to get the catalog data.

This can only be set on the global profile.

This defaults to https://d1i21q4vxgce8j.cloudfront.net/rackn-catalog.json.

Another option is https://s3-us-west-2.amazonaws.com/rebar-catalog/rackn-catalog.json.

24.15.2.4.57. network-data-parser-debug

If set to boolean true, will output execution environment specific echo/print statements for deugging how the parser interpretted the `network-data structure. The bare variables (eg $_nd_address) and the more complex data structure (associative array, dict, or hash table) will both be printed out.

24.15.2.4.58. part-scheme

This string contains the name of a template that holds the Debian installer partitioning commands for use during installation.

The string will be expanded into this template name:

part-seed-<string>.tmpl

e.g. softraid

24.15.2.4.59. provisioner-selinux-type

Defines the SELinux mode to set on a system during installation.

Also see provisioner-selinux

24.15.2.4.60. select-kickseed

The name of a custom kickstart or preseed template to use. If not defined, the default for each platform will be used, as follows

'net-seed.tmpl' for Debian/Ubuntu platforms
'centos-7.ks.tmpl' for CentOS 7 platforms

24.15.2.4.61. os-identity/system

The value of the Operating System type, as discovered and set by the task os-identity.

24.15.2.4.62. rs-debug-enable

Boolean value that enables Bash Script debugging - essentially by turning on ‘set -x’ globally. Scripts can (and probably do) enable/disable this flags in various sections. In those cases we are not overriding those values.

Additionally, the shell variable ‘RS_DEBUG_ENABLE’ is set to 1 (on) for Script authors to use. This allows a construct like

(( $RS_DEBUG_ENABLE )) && run_debug_function

24.15.2.4.63. sledgehammer/reboot-if-not-in-sledgehammer

Boolean parameter indicating if the enforce-sledgehammer task should reboot the system if not in sledgehammer.

24.15.2.4.64. sledgehammer/working-python

This param can be set to one of three different values:

  1. auto, which will remove /the /usr/bin/python link. When auto is in use, your Python scripts will need to explicitly choose which python interpreter to use, either via the #! line at the start of the script or via more ornate means.
  2. /usr/bin/python2, which will point /usr/bin/python to python2
  3. /usr/bin/python3, which will point /usr/bin/python to python3

24.15.2.4.65. access-keys-global

Supplements local access-keys by adding global keys (generall from the global profile) Generally, access-keys are to be set for narrow use cases such as per machine.

This map is used to put additional ssh public keys in place for the root user.

The key of the map is a arbritary name and the value is the ssh public key for that name.

Parameter YAML format:

access-keys:
  greg:  ssh-rsa key
  greg2:  ssh-rsa key

24.15.2.4.66. linux/install-bootenv-override

This string defines a specific bootenv name.

24.15.2.4.67. net/interface-config

This parameter defines how nics created by the network/interface-topology param should have their addressing and routing configured. It consists of an object whose keys are netplan IDs and whose values are objects containing values listed in https://netplan.io/reference#common-properties-for-all-device-types.

Any netplan IDs listed here that are not present in network/interface-topology will be treated like they refer to ethernet devices with the same name as the netplan id.

The default value of this parameter is:

bootif:
  dhcp4: true

which specifies that we should write out a configuration that has the interface we booted from configure itself using DHCPv4.

When the network configuration on a machine is generated using the drpcli net generate command, the configuration for the netplan IDs are merged with the coresponding netplan IDs in the net/interface-topology param, with any extra IDs being added as-is to the ethernets section of that param. Note that a netplan ID is not necessarily the same thing as a device name, nor does it have to uniquely map to a single device. For example, if we have a net/interface-topology of

network:
  version: 2
  ethernets:
    onboards:
      match:
        name: onboard:*

we can have all of them use DHCP4 and 6 to get their addresses like so:

onboards:
  dhcp4: true
  dhcp6: true

24.15.2.4.68. ntp-servers

This is an array of strings where each string an IP address or Name of an NTP server. Used by the Debian & Ubuntu installers only at this time.

24.15.2.5. stages

The content package provides the following stages.

24.15.2.5.1. complete-nowait

This is deprectated and leaves the runner running, but will exit install bootenvs correctly. The use of this was to exit install workflows. This will continue to work for that, but should be replaced by finish-install.

24.15.2.5.2. empty-gpt-tables

For every disk found in the system, write an empty GPT table on the disk. This typically should follow the prep-install Stage which wipes the disks clean.

Useful for disks destined for VMware vSphere VSAN or other storage solutions that require starting with a clean disk with an empty GPT table to use the disk.

24.15.2.5.3. exit-context

It can be handy to have a stage-based marker for switching back to the default context. This stage provides that.

24.15.2.5.4. network-manage-routes

This stage uses the network-data structure to set or remove any routes specified based on the reference tag named in network-data-tag Param setting.

The action of add or remove is controlled by the Param network-manage-routes-command, which defaults to adding routes to a system.

An example of network-data Param values known to work with this Stage are as follows (the Param network-data-tag would be set to myroutes in this example):

in YAML format:
network-data:
  myroutes:
    routes:
    - gateway: 192.168.100.1
      netmask: 255.255.255.0
      network: 10.10.10.0
    - gateway: 172.17.92.254
      netmask: 255.255.255.0
      network: 10.20.20.0

in JSON Format:

{
  "myroutes": {
    "routes": [
      { "gateway": "192.168.100.1", "netmask": "255.255.255.0", "network": "10.10.10.0" },
      { "gateway": "172.17.92.254", "netmask": "255.255.255.0", "network": "10.20.20.0" }
    ]
  }
}

Note

The network-data structure is used for other network plumbing purposes too. This example only shows valid syntax for adding routes. Additional stanzas are likely to appear in a valid data structure. See the documentation on the Param for more details.

24.15.2.5.5. os-identity

This Stage sets the Operating System identity Params on the Machine object.

24.15.2.5.6. bootstrap-base

Bootstrap stage to builds out the minimal setup

The following things are done:

  • Make sure the prefs are set correctly
  • Make and install a public/private key pair for ssh access to clients.
  • Make sure sledgehammer iso is loaded
  • Lock the machine to prevent accidental changes

24.15.2.5.7. discover-no-gohai

DEPRECATED! Use the discover Stage with gohai/skip Param instead.

Pre gohai/skip Parameter, used to run discovery without gohai action.

24.15.2.5.8. discover-nobootenv

Specialized version of Discovery to be used with machines that use the join-up.sh process.

This stage is the typical first entry point for cloud and externally created machines outside of the normal Digital Rebar discovery process.

If you are using sledgehammer then use the regular discover Stage.

24.15.2.5.9. finish-install

Originally, this stage was used with the STOP runner action in the change-stage/map.

Going forward, the STOP action is not required. The changing of bootenv from something-install to local will cause the runner to exit. This stage will cause an install bootenv to reboot because the bootenv is changed to local.

24.15.2.5.10. ubuntu-18.04-install

Installs the GA (General Availability) kernel by default. To install the HWE kernel, please set the “ubuntu-hwe-kernel” Param on your machine and set it to “true” (use Param, Profile, or “global” Profile).

Note for HWE kernel, the BootEnv “.Env.OS.Version” value is used to set the HWE preseed option correctly. Please verify that the preseed syntax is valid for your version of Ubuntu (this was tested working with 18.04).

24.15.2.5.11. discover

Default machine discovery process used for bare metal.

This stage is the typical first entry point for all machines using standard Digital Rebar discovery processes.

This stage expects and enforces sledgehammer as the BootEnv. If the machine is not using sledgehammer then use discover-nobootenv.

24.15.2.5.12. ssh-access

Installs SSH keys onto systems Pulls keys from multiple locations: access-keys, access-keys-shared, and access-keys-global

24.15.2.5.13. set-machine-name-from-hostname

This Stage sets the Machine Object .Machine.Name value to the current Machine objects Parameter named hostname. This is often used in discovery stages, where the Classify functions may set a Machines Param hostname to a value based on the classify actions.

This Stage should be run after any Classify action Stages which perform add_parameter hostname BOB actions - or similar Stages that set the Machine objects hostname Param.

24.15.2.5.14. complete

This stage is used to indicate the completion of a workflow that expects the runner to be running on the machine in a local boot environment. This should NOT be used by workflows running in contexts unless the goal is to transition back to the machine.

24.15.2.5.15. ubuntu-20.04-install

Installs the GA (General Availability) kernel by default. To install the HWE kernel, please set the “ubuntu-hwe-kernel” Param on your machine and set it to “true” (use Param, Profile, or “global” Profile).

Note for HWE kernel, the BootEnv “.Env.OS.Version” value is used to set the HWE preseed option correctly. Please verify that the preseed syntax is valid for your version of Ubuntu (this was tested working with 18.04).