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 between 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 example, 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