1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 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 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
|