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
|
