DataONE CN OS Core postinst and ConfigurationΒΆ

Each DataONE CN maintains a debian backend database named ‘dataone-cn-os-core’. The database is populated by the dataone-cn-os-core debian package. Debian package installation for DataONE requires data input to the dataone-cn-os-core debian backend database for each environment, and sometimes each CN, such as IP address, passwords, node Ids, etc. Debian installation scripts can read the data written to the ‘dataone-cn-os-core’ debian backend database and use the data to configure software. In order to lessen the amount of typing (and errors) during the debian installation process, debian configuration is automated as much as possible.

The debian backend database is setup during a debian installation by the availability of a templates file. The templates file contains multiple variable names (database fields), each a ‘Template’. Each ‘Template’ has a question to ask a user and the data type of the ‘Template’ to be persisted in the debian backend database. Typically, a debian preinst script is used to decide which questions will be asked to a user during installation. DataONE uses a different strategy.

DataONE debian installation uses an xml configuration (d1DebConfig.xml) file to fill in the ‘Template’ variable (field) questions that would typically be asked to a user. d1DebConfig.xml is evaluated by the dataone-cn-os-core package’s postinst script during debian installation. d1DebConfig.xml is divided into two parts. The first part mimics the templates file in the debian installation, the second part contains the data that debian expects the user to answer. Each ‘template’ node in d1DebConfig.xml contains a key that is the field name associated with a debian ‘Template’. A ‘template’ node contains the question of the template, the type of the template and various flags. The flags and the field name are the most important. There are DataONE configuration specific flags for each ‘template’ node. The ‘derived-value’ flag, the ‘user-entered-value’ flag and the ‘configured-value’ flag must each be set for each template. Only one of the three flags should be set to true. The ‘derived-value’ flag indicates to the postinst script that the value of the field is set programmatically by the postinst script. For each ‘derived-value’ flag, there is custom logic in postinst to populate the debian backend database. The ‘user-entered-value’ flag prompts the user for input in the traditional way that a debian package installation would. The ‘configured-value’ flag indicates that postinst is able to parse the value of the field from d1DebConfig.xml.

The second part of the d1DebConfig.xml contains the data for each of the templates defined in the first half of the file. In the second part of d1DebConfig.xml are ‘environment’ nodes. ‘environment’ nodes contain answers to questions or contain ‘machine’ nodes that then contain answers to questions. Each ‘environment’ node has a context key that names the environment to which the answers or machines belong. Each template in the first half of d1DebConfig.xml should have an answered question in the second half for each environment. If the question is a machine dependent question, then the ‘question’ node should a child of a ‘machine’ node. If the question is the same for every machine of an environment, then the ‘question’ node should be a child of an ‘environment’ node. For ‘derived-value’ and ‘user-entered-value’ flagged questions, the ‘question’ node should be left empty.

The steps below demonstrate how to ask for user input during debian installation of a package. The assumption is that the user input will be applied to configuration settings of a downstream dataone package.

  1. A new entry in the debian templates file for the new template should be added. The location of this file is: https://repository.dataone.org/software/cicore/trunk/cn-buildout/dataone-cn-os-core/DEBIAN/templates
  2. A new ‘template’ node that mimics the information in the debian templates file should be added to d1DebConfig.xml. As noted above, the values of the flags should be ‘derived-value’ false, ‘user-entered-value’ true, and ‘configured-value’ false.
  3. A new ‘question’ node should be added to each environment, but should be left empty.
  4. Lastly, in postinst, each ‘user-entered-value’ question will be re-asked each time by dataone-cn-os-core unless specifically excluded. The function ‘resetDebQuestionSeenFlag’ in https://repository.dataone.org/software/cicore/trunk/cn-buildout/dataone-cn-os-core/DEBIAN/postinst should be edited to exclude the new template. If the value of the field needs to be altered in the future, then the backend database will need to be modified through a stand-alone bash script.
  5. dataone-cn-os-core will not use the new data to configure software. The software applying the data is dependent upon dataone-cn-os-core and will be installed after dataone-cn-os-core. For example, the postinst script of the dataone-cn-portal package would have lines added where the new template is read and then write logic to alter the configuration of the dataone-cn-portal install.

As a note, the postinst script requires datastructures to maintain the information parsed from xml files and to evaluate if data in the backend database should be changed upon upgrade. Debian requires the use of shell scripts (bash) for postinst. Unfortunately, bash is fairly weak when it comes to datastructures and so the postinst code to maintain automated configuration is fairly complicated. This complication is in addition to the code needed to configure 8 different software packages for Dataone, LDAP being the most complicated. The dataone-cn-os-core postinst code must be run before any other dataone debian package may install correctly.

Additonal Resources:

This material is based upon work supported by the National Science Foundation under Grant Numbers 083094 and 1430508.

Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.