Add a document that sets out the desired end goal for the database organization that the following patches will move towards. Signed-off-by: Daniel P. Berrange <berrange@xxxxxxxxxx> --- docs/database-layout.txt | 224 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 docs/database-layout.txt diff --git a/docs/database-layout.txt b/docs/database-layout.txt new file mode 100644 index 0000000..40374b1 --- /dev/null +++ b/docs/database-layout.txt @@ -0,0 +1,224 @@ + The Libosinfo Database Layout + ============================= + +This document specifies the layout of the libosinfo database and +details the process by which data files must be loaded by any +compliant applications consuming the database. + + +Entities +======== + +The purpose of the database is to store information related to +a number of entity types that are relevant when provisioning +virtual machines. + + - OS - a guest operating system + - Platform - a host virtualization platform + - Device - a hardware device + - Install Script - script for automated installation of an OS + - Data map - a mapping betweeen two datasets + - Deployment - an association of an OS on a Platform + +Each of these entities has a variety of pieces of information +associated with it. There are also relationships between many +of the entities. + +The path component of the entity ID URI will be used to form +the filename of the XML document on disk. + + +Database locations +================== + +There are a number of standard directory locations which +together form the database. + + + - System location + + This is determined by the env variable + + $OSINFO_SYSTEM_DIR + + If not set, then defaults to /usr/share/osinfo + + This location is intended for use by operating system + distributors to install the initial data set via a + package management system like RPM or Deb + + + - Local location + + This is determined by the env variable + + $OSINFO_LOCAL_DIR + + If not set, then defaults to /etc/osinfo + + This location is intended for use by local system + administrators to install custom local data that + should be available to all users on a host + + + - User location + + This is determined by the env variable + + $OSINFO_USER_DIR + + If not set, then defaults to $XDG_CONFIG_HOME/osinfo + + If that is not set, then defaults to $HOME/.config/osinfo + + This location is intended for use by unprivileged users + wishing to install local data for use by their applications + +A compliant implementation MUST load data from all the standard +locations declared in this document. An implementation MAY wish +to load data from additional non-standard locations depending +on application requirements. + +When loading entities from these locations, if the same +entity is present in multiple locations, the entity found +in the later location MUST take priority over the entity +found in the earlier locations. The next section details how +entities are named. + + +File naming +=========== + +Within each of the database locations mentioned above, there are +a number of file naming requirements that must be followed. + +First level directory +--------------------- + +The first (top) level directory within the database location +MUST only contain the following entries + + - os + - platform + - install-script + - datamap + - device + - deployment + +Each of these entries MUST be a directory, any other type of +file MUST NOT be loaded and a warning SHOULD be reported. +An entry MAY be omitted if there are no files to be stored +within it. + +These directory entries correspond to the types of entity +that are stored in the osinfo database. + + +Second level directory +---------------------- + +The second level directories within the database location are +used to group entities based on domain names from the entity +ID URI. + +For exaxple, if an entity has a URI + + http://fedoraproject.org/fedora/22 + +Then there will be a second level directory named +"fedoraproject.org" + +All entries in the second level MUST be directories, any +other type of file MUST NOT be loaded an a warning SHOULD +be reported. + + +Third level directory +--------------------- + +Within the thread level directories there may be further files +or directories with the following naming + + - ENTITY-NAME.xml + - ENTITY-NAME.d + +The ENTITY-NAME string MUST only contain characters from the +following set + + - Letters: a-z, A-Z + - Numbers: 0-9 + - Punctuation: _ - . + +Any file or directory names not matching these rules MUST be +ignored when loading the database, and a warning SHOULD be +reported. + +If both ENTITY-NAME.xml and ENTITY-NAME.d are present for a +common value of ENTITY-NAME, then ENTITY-NAME.xml MUST be +loaded before the contents of ENTITY-NAME.d are loaded. + +The ENTITY-NAME value is formed from the path component +of the entity ID URI. Any characters in the path component +which are not in the permitted set MUST be replaced by a +'-' character. + +For example, an entity ID of http://fedoraproject.org/fedora/22 +will result in an ENTITY-NAME of "fedora-22", since '/' is to +be substituted with '-'. + + +ENTITY-NAME.xml +--------------- + +This entry should either be a regular file, or a symbolic link +to /dev/null. If another file type is found, the file MUST NOT +be loaded and a warning SHOULD be reported. + +If the file is zero-length or points to /dev/null, then this +represents a black-out override. This indicates that the +ENTITY-NAME.xml file from a lower priority directory MUST NOT +be loaded. + +If the file is non-zero-length then its contents MUST be a +single entity with a URI that matches the file path of the +XML file relative to the location root. + +For example, if the file path is + + /etc/osinfo/os/fedoraproject.org/fedora-22.xml + +the, the file MUST contain a operating system entity definition +for the operating system with id http://fedoraproject.org/fedora-22.xml. +If the entity type does not match the directory in which the +file was located, the file MUST NOT be loaded and a warning +SHOULD be reported + + +ENTITY-NAME.d +------------- + +This entry MUST be a directory, if another file type is found +this entry MUST NOT be loaded and a warning SHOULD be reported + +Within this second level directories there may be further files +with the following naming + + - FILE-NAME.xml + +The FILE-NAME string MUST only contain characters from the +following set + + - Letters: a-z, A-Z + - Numbers: 0-9 + - Punctuation: _ - . + +Any file or directory names not matching these rules MUST be +ignored when loading the database, and a warning SHOULD be +reported. + +The FILE-NAME.xml must be a regular file, any other type +of file MUST NOT be loaded and a warning SHOULD be reported + +The contents of each FILE-NAME.xml found are used to augment +information associated with the entity identified by +ENTITY-NAME.d -- 2.4.3 _______________________________________________ Libosinfo mailing list Libosinfo@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libosinfo
