Bootstrap
Bootstrap is the process whereby, after a VM is started for the first time, it is configured with key system-level configuration such as IP addresses, DNS and NTP server addresses, a hostname, and so on. This process runs automatically on the first boot of the VM. In order for bootstrap to succeed it is crucial that all entries in the SDF (or in the case of a manual deployment, all the bootstrap parameters) are correct.
Successful bootstrap
Once the VM has booted into multi-user mode, bootstrap normally takes about one minute.
SSH access to the VM is not possible until bootstrap has completed. If you want to monitor
bootstrap from the console, log in as the sentinel user with password !sentinel and examine the log file bootstrap/bootstrap.log.
Successful completion is indicated by the line Bootstrap complete.
Troubleshooting bootstrap
If bootstrap fails, an exception will be written to the log file. If the network-related portion
of bootstrap succeeded but a failure occurred afterwards, the VM will be accessible over SSH and
logging in will display a warning Automatic bootstrap failed.
Examine the log file bootstrap/bootstrap.log to see why bootstrap failed. In the majority of cases
it will be down to an incorrect SDF or a missing or invalid bootstrap parameter. Destroy the VM and recreate it with
the correct SDF or bootstrap parameters (it is not possible to run bootstrap more than once).
If you are sure you have the SDF or bootstrap parameters correct, or it is not obvious what is wrong, then contact your Customer Care Representative.
Initial configuration
Initial configuration occurs after bootstrap. It sets up product-level configuration such as:
-
configuring Rhino and the relevant Sentinel products (on systems that run Rhino);
-
SNMP-based monitoring; and
-
SSH key exchange to allow access from other VMs in the cluster to this VM.
To perform this initial configuration, the process retrieves its configuration in the form of YAML files from the CDS (Config Data Store). The CDS to contact is determined using the 'CDS addresses' parameter from the SDF or bootstrap parameters. Currently CDS services are provided by the TSN nodes.
The YAML files describing the initial configuration should be prepared in advance, and uploaded to the CDS after spinning up the VMs using the process described below.
Configuration files
The initial configuration process reads settings from YAML files. Each YAML file refers to a particular set of configuration options, for example SNMP settings. The YAML files are validated against a YANG schema. The YANG schema is human-readable and lists all the possible options, together with a description. It is therefore recommended to reference the Initial configuration YANG schema while preparing the YAML files.
Some YAML files are shared between different node types. If a file with the same file name is required for two different node types, then the same file must be used in both cases.
A set of sample YAML files for ShCM nodes can be found on the Example initial configuration YAML files page.
|
Since TSN nodes provide the CDS services, boot all TSN nodes and wait for them to complete bootstrap before booting a node of any other type. |
|
|
When uploading configuration files, you must also include Solution Definition Files for all RVT nodes in the deployment (see below). Furthermore, for any VM which runs Rhino, you must also include a valid Rhino license. |
Solution Definition Files
If performing an automated deployment, you will already have written Solution Definition Files (SDFs) as part of the creation of the VMs. However, as the initial configuration process discovers other RVT nodes using the SDFs, even when performing a manual deployment, you are still required to write SDFs. Read the page on preparing an SDF for more details on how to write an SDF.
|
|
When writing an SDF for a manual deployment, it is not necessary to fill out any connectivity information, including credentials, for the VMware or OpenStack deployment. However, all other fields, in particular hostnames, the deployment ID, the site ID and all the IPs must be filled out correctly. |
|
|
The SDF for this node type should be in a file named |
The rvtconfig tool
Initial configuration YAML files can be validated and uploaded to CDS using the rvtconfig tool.
It is possible to run the rvtconfig tool either from the Commissioning VM, or from any Rhino VoLTE TAS (RVT) VM.
On the Commissioning VM, the command can be found in the resources subdirectory of
any RVT CSAR, e.g.:
/home/admin/.local/share/csar/tsn-vmware-csar/resources/rvtconfig.
On any RVT VM, the rvtconfig tool is on the path for the sentinel user and can be run directly by running rvtconfig.
The tool current supports the following three commands:
-
rvtconfig validatecan be used to validate the configuration, even before booting any RVT VMs by using the Commissioning VM. -
rvtconfig initial-configurecan be used to upload the configuration to CDS. -
rvtconfig delete-deploymentcan be used to delete a deployment from CDS - only use this when advised to do so by your Customer Care Representative.
For more information, use the built-in help, i.e. run rvtconfig --help.
Uploading configuration to CDS
To upload the YAML files to CDS:
-
Create a directory to hold the initial configuration YAML files:
mkdir yamls -
Upload all the files to this directory: the initial configuration YAML files, the Solution Definition Files (SDFs) for all node types, and the Rhino license for nodes running Rhino. Ensure all the files are in the directory itself - do not create any subdirectories. Also ensure the file names match the example YAML files.
-
Validate the YAML files using the
rvtconfigtool:rvtconfig validate -l -t shcm -i ~/yamlsThe
rvtconfigcommand can be run from the Commissioning VM, or alternatively you can SSH into any TSN VM and run the command from there (see the previous section for more details). If there are any errors, fix them, upload the fixed files to theyamlsdirectory, and then re-run the abovervtconfig validatecommand. -
Once the files pass validation, store the YAML files in CDS using the
rvtconfigtool:rvtconfig initial-configure -c <Any TSN VM’s management IP address> -d <deployment ID> -t shcm -i ~/yamlsIf the CDS is not yet available, this will retry every 30 seconds for up to 15 minutes. As a large TSN cluster can take up to one hour to form, this means the command could time out before it completes. If the command still fails after several attempts over an hour, troubleshoot the TSN nodes.
|
If using the Commissioning VM, the |
Successful initial configuration
The initial configuration process on the VMs starts after bootstrap completes. It is constantly listening for configuration to be written to CDS (see above). Once it detects configuration has been uploaded, it will automatically download and validate it. Assuming everything passes validation, the configuration will then be applied automatically. This can take up to 20 minutes depending on node type.
You can monitor the initial configuration process by using the report-initconf status tool.
Success is indicated by status=vm_converged.
Troubleshooting initial configuration
Like bootstrap, errors are reported to the log file.
<file> failed to validate against YANG schemas: This indicates something in one of the YAML files
was invalid. Refer to the output to check which field was invalid, and fix the problem. For initial
configuration validation issues you do not have to destroy and recreate the VM, but can simply
upload the fixed configuration using rvtconfig as per the instructions above.
The initial configuration process will automatically try again once it detects the uploaded
configuration has been updated.
Task <name> caused an error: This indicates that initial configuration has irrecoverably failed.
Contact your Customer Care Representative for next steps.
Other errors: If these relate to invalid field values or a missing license then it is normally safe to fix the configuration and try again. Otherwise, contact your Customer Care Representative.
