1 /*
2  * storage_source_conf.h: file utility functions for FS storage backend
3  *
4  * Copyright (C) 2007-2009, 2012-2016 Red Hat, Inc.
5  * Copyright (C) 2007-2008 Daniel P. Berrange
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public
9  * License as published by the Free Software Foundation; either
10  * version 2.1 of the License, or (at your option) any later version.
11  *
12  * This library is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public
18  * License along with this library.  If not, see
19  * <http://www.gnu.org/licenses/>.
20  */
21 
22 #pragma once
23 
24 #include "storage_encryption_conf.h"
25 #include "virbitmap.h"
26 #include "virconftypes.h"
27 #include "virenum.h"
28 #include "virobject.h"
29 #include "virpci.h"
30 #include "virseclabel.h"
31 #include "virsecret.h"
32 
33 /* Types of disk backends (host resource).  Comparable to the public
34  * virStorageVolType, except we have an undetermined state, don't have
35  * a netdir type, and add a volume type for reference through a
36  * storage pool.  */
37 typedef enum {
38     VIR_STORAGE_TYPE_NONE,
39     VIR_STORAGE_TYPE_FILE,
40     VIR_STORAGE_TYPE_BLOCK,
41     VIR_STORAGE_TYPE_DIR,
42     VIR_STORAGE_TYPE_NETWORK,
43     VIR_STORAGE_TYPE_VOLUME,
44     VIR_STORAGE_TYPE_NVME,
45     VIR_STORAGE_TYPE_VHOST_USER,
46 
47     VIR_STORAGE_TYPE_LAST
48 } virStorageType;
49 
50 VIR_ENUM_DECL(virStorage);
51 
52 
53 typedef enum {
54     VIR_STORAGE_FILE_AUTO_SAFE = -2,
55     VIR_STORAGE_FILE_AUTO = -1,
56     VIR_STORAGE_FILE_NONE = 0,
57     VIR_STORAGE_FILE_RAW,
58     VIR_STORAGE_FILE_DIR,
59     VIR_STORAGE_FILE_BOCHS,
60     VIR_STORAGE_FILE_CLOOP,
61     VIR_STORAGE_FILE_DMG,
62     VIR_STORAGE_FILE_ISO,
63     VIR_STORAGE_FILE_VPC,
64     VIR_STORAGE_FILE_VDI,
65 
66     /* Not direct file formats, but used for various drivers */
67     VIR_STORAGE_FILE_FAT,
68     VIR_STORAGE_FILE_VHD,
69     VIR_STORAGE_FILE_PLOOP,
70 
71     /* Not a format, but a marker: all formats below this point have
72      * libvirt support for following a backing chain */
73     VIR_STORAGE_FILE_BACKING,
74 
75     VIR_STORAGE_FILE_COW = VIR_STORAGE_FILE_BACKING,
76     VIR_STORAGE_FILE_QCOW,
77     VIR_STORAGE_FILE_QCOW2,
78     VIR_STORAGE_FILE_QED,
79     VIR_STORAGE_FILE_VMDK,
80 
81     VIR_STORAGE_FILE_LAST,
82 } virStorageFileFormat;
83 
84 VIR_ENUM_DECL(virStorageFileFormat);
85 
86 
87 typedef enum {
88     VIR_STORAGE_FILE_FEATURE_LAZY_REFCOUNTS = 0,
89 
90     VIR_STORAGE_FILE_FEATURE_LAST
91 } virStorageFileFeature;
92 
93 VIR_ENUM_DECL(virStorageFileFeature);
94 
95 
96 typedef struct _virStoragePerms virStoragePerms;
97 struct _virStoragePerms {
98     mode_t mode;
99     uid_t uid;
100     gid_t gid;
101     char *label;
102 };
103 
104 
105 typedef struct _virStorageTimestamps virStorageTimestamps;
106 struct _virStorageTimestamps {
107     struct timespec atime;
108     struct timespec btime; /* birth time unknown if btime.tv_nsec == -1 */
109     struct timespec ctime;
110     struct timespec mtime;
111 };
112 
113 
114 /* Information related to network storage */
115 typedef enum {
116     VIR_STORAGE_NET_PROTOCOL_NONE,
117     VIR_STORAGE_NET_PROTOCOL_NBD,
118     VIR_STORAGE_NET_PROTOCOL_RBD,
119     VIR_STORAGE_NET_PROTOCOL_SHEEPDOG,
120     VIR_STORAGE_NET_PROTOCOL_GLUSTER,
121     VIR_STORAGE_NET_PROTOCOL_ISCSI,
122     VIR_STORAGE_NET_PROTOCOL_HTTP,
123     VIR_STORAGE_NET_PROTOCOL_HTTPS,
124     VIR_STORAGE_NET_PROTOCOL_FTP,
125     VIR_STORAGE_NET_PROTOCOL_FTPS,
126     VIR_STORAGE_NET_PROTOCOL_TFTP,
127     VIR_STORAGE_NET_PROTOCOL_SSH,
128     VIR_STORAGE_NET_PROTOCOL_VXHS,
129     VIR_STORAGE_NET_PROTOCOL_NFS,
130 
131     VIR_STORAGE_NET_PROTOCOL_LAST
132 } virStorageNetProtocol;
133 
134 VIR_ENUM_DECL(virStorageNetProtocol);
135 
136 
137 typedef enum {
138     VIR_STORAGE_NET_HOST_TRANS_TCP,
139     VIR_STORAGE_NET_HOST_TRANS_UNIX,
140     VIR_STORAGE_NET_HOST_TRANS_RDMA,
141 
142     VIR_STORAGE_NET_HOST_TRANS_LAST
143 } virStorageNetHostTransport;
144 
145 VIR_ENUM_DECL(virStorageNetHostTransport);
146 
147 
148 typedef struct _virStorageNetHostDef virStorageNetHostDef;
149 struct _virStorageNetHostDef {
150     char *name;
151     unsigned int port;
152     int transport; /* virStorageNetHostTransport */
153     char *socket;  /* path to unix socket */
154 };
155 
156 
157 typedef struct _virStorageNetCookieDef virStorageNetCookieDef;
158 struct _virStorageNetCookieDef {
159     char *name;
160     char *value;
161 };
162 
163 
164 void
165 virStorageNetCookieDefFree(virStorageNetCookieDef *def);
166 
167 G_DEFINE_AUTOPTR_CLEANUP_FUNC(virStorageNetCookieDef, virStorageNetCookieDefFree);
168 
169 
170 /* Information for a storage volume from a virStoragePool */
171 
172 /*
173  * Used for volume "type" disk to indicate how to represent
174  * the disk source if the specified "pool" is of iscsi type.
175  */
176 typedef enum {
177     VIR_STORAGE_SOURCE_POOL_MODE_DEFAULT = 0,
178 
179     /* Use the path as it shows up on host, e.g.
180      * /dev/disk/by-path/ip-$ip-iscsi-$iqn:iscsi.iscsi-pool0-lun-1
181      */
182     VIR_STORAGE_SOURCE_POOL_MODE_HOST,
183 
184     /* Use the URI from the storage pool source element host attribute. E.g.
185      * file=iscsi://demo.org:6000/iqn.1992-01.com.example/1.
186      */
187     VIR_STORAGE_SOURCE_POOL_MODE_DIRECT,
188 
189     VIR_STORAGE_SOURCE_POOL_MODE_LAST
190 } virStorageSourcePoolMode;
191 
192 VIR_ENUM_DECL(virStorageSourcePoolMode);
193 
194 
195 typedef struct _virStorageSourcePoolDef virStorageSourcePoolDef;
196 struct _virStorageSourcePoolDef {
197     char *pool; /* pool name */
198     char *volume; /* volume name */
199     int voltype; /* virStorageVolType, internal only */
200     int pooltype; /* virStoragePoolType from storage_conf.h, internal only */
201     int actualtype; /* virStorageType, internal only */
202     int mode; /* virStorageSourcePoolMode, currently makes sense only for iscsi pool */
203 };
204 
205 
206 typedef enum {
207     VIR_STORAGE_AUTH_TYPE_NONE,
208     VIR_STORAGE_AUTH_TYPE_CHAP,
209     VIR_STORAGE_AUTH_TYPE_CEPHX,
210 
211     VIR_STORAGE_AUTH_TYPE_LAST,
212 } virStorageAuthType;
213 
214 VIR_ENUM_DECL(virStorageAuth);
215 
216 
217 typedef struct _virStorageAuthDef virStorageAuthDef;
218 struct _virStorageAuthDef {
219     char *username;
220     char *secrettype; /* <secret type='%s' for disk source */
221     int authType;     /* virStorageAuthType */
222     virSecretLookupTypeDef seclookupdef;
223 };
224 
225 
226 typedef struct _virStoragePRDef virStoragePRDef;
227 struct _virStoragePRDef {
228     int managed; /* enum virTristateBool */
229     char *path;
230 
231     /* manager object alias */
232     char *mgralias;
233 };
234 
235 
236 typedef struct _virStorageSourceInitiatorDef virStorageSourceInitiatorDef;
237 struct _virStorageSourceInitiatorDef {
238     char *iqn; /* Initiator IQN */
239 };
240 
241 
242 typedef struct _virStorageSourceNVMeDef virStorageSourceNVMeDef;
243 struct _virStorageSourceNVMeDef {
244     unsigned long long namespc;
245     virTristateBool managed;
246     virPCIDeviceAddress pciAddr;
247 
248     /* Don't forget to update virStorageSourceNVMeDefCopy */
249 };
250 
251 
252 typedef struct _virStorageSourceSlice virStorageSourceSlice;
253 struct _virStorageSourceSlice {
254     unsigned long long offset;
255     unsigned long long size;
256     char *nodename;
257 };
258 
259 
260 typedef struct _virStorageSource virStorageSource;
261 
262 /* Stores information related to a host resource.  In the case of backing
263  * chains, multiple source disks join to form a single guest view.
264  *
265  * IMPORTANT: When adding fields to this struct it's also necessary to add
266  * appropriate code to the virStorageSourceCopy deep copy function */
267 struct _virStorageSource {
268     virObject parent;
269 
270     unsigned int id; /* backing chain identifier, 0 is unset */
271     int type; /* virStorageType */
272     char *path;
273     int protocol; /* virStorageNetProtocol */
274     char *volume; /* volume name for remote storage */
275     char *snapshot; /* for storage systems supporting internal snapshots */
276     char *configFile; /* some storage systems use config file as part of
277                          the source definition */
278     char *query; /* query string for HTTP based protocols */
279     size_t nhosts;
280     virStorageNetHostDef *hosts;
281     size_t ncookies;
282     virStorageNetCookieDef **cookies;
283     virStorageSourcePoolDef *srcpool;
284     virStorageAuthDef *auth;
285     virStorageEncryption *encryption;
286     virStoragePRDef *pr;
287     virTristateBool sslverify;
288     /* both values below have 0 as default value */
289     unsigned long long readahead; /* size of the readahead buffer in bytes */
290     unsigned long long timeout; /* connection timeout in seconds */
291 
292     virStorageSourceNVMeDef *nvme; /* type == VIR_STORAGE_TYPE_NVME */
293 
294     virDomainChrSourceDef *vhostuser; /* type == VIR_STORAGE_TYPE_VHOST_USER */
295 
296     virStorageSourceInitiatorDef initiator;
297 
298     virObject *privateData;
299 
300     int format; /* virStorageFileFormat in domain backing chains, but
301                  * pool-specific enum for storage volumes */
302     virBitmap *features;
303     char *compat;
304     bool nocow;
305     bool sparse;
306 
307     virStorageSourceSlice *sliceStorage;
308 
309     virStoragePerms *perms;
310     virStorageTimestamps *timestamps;
311     unsigned long long capacity; /* in bytes, 0 if unknown */
312     unsigned long long allocation; /* in bytes, 0 if unknown */
313     unsigned long long physical; /* in bytes, 0 if unknown */
314     unsigned long long clusterSize; /* in bytes, 0 if unknown */
315     bool has_allocation; /* Set to true when provided in XML */
316 
317     unsigned long long metadataCacheMaxSize; /* size of the metadata cache in bytes */
318 
319     size_t nseclabels;
320     virSecurityDeviceLabelDef **seclabels;
321 
322     /* Don't ever write to the image */
323     bool readonly;
324 
325     /* image is shared across hosts */
326     bool shared;
327 
328     /* backing chain of the storage source */
329     virStorageSource *backingStore;
330 
331     /* metadata for storage driver access to remote and local volumes */
332     void *drv;
333 
334     /* metadata about storage image which need separate fields */
335     /* Relative name by which this image was opened from its parent, or NULL
336      * if this image was opened by absolute name */
337     char *relPath;
338     /* Name of the child backing store recorded in metadata of the
339      * current file.  */
340     char *backingStoreRaw;
341     virStorageFileFormat backingStoreRawFormat;
342 
343     /* metadata that allows identifying given storage source */
344     char *nodeformat;  /* name of the format handler object */
345     char *nodestorage; /* name of the storage object */
346 
347     /* An optional setting to enable usage of TLS for the storage source */
348     virTristateBool haveTLS;
349 
350     /* Indication whether the haveTLS value was altered due to qemu.conf
351      * setting when haveTLS is missing from the domain config file */
352     bool tlsFromConfig;
353 
354     /* If TLS is used, then mgmt of the TLS credentials occurs via an
355      * object that is generated using a specific alias for a specific
356      * certificate directory with listen and verify bools. */
357     char *tlsAlias;
358     char *tlsCertdir;
359 
360     bool detected; /* true if this entry was not provided by the user */
361 
362     unsigned int debugLevel;
363     bool debug;
364 
365     /* Libvirt currently stores the following properties in virDomainDiskDef.
366      * These instances are currently just copies from the parent definition and
367      * are not mapped back to the XML */
368     int iomode; /* enum virDomainDiskIo */
369     int cachemode; /* enum virDomainDiskCache */
370     int discard; /* enum virDomainDiskDiscard */
371     int detect_zeroes; /* enum virDomainDiskDetectZeroes */
372 
373     bool floppyimg; /* set to true if the storage source is going to be used
374                        as a source for floppy drive */
375 
376     bool hostcdrom; /* backing device is a cdrom */
377 
378     /* passthrough variables for the ssh driver which we don't handle properly */
379     /* these must not be used apart from formatting the output JSON in the qemu driver */
380     char *ssh_user;
381     bool ssh_host_key_check_disabled;
382 
383     /* nfs_user and nfs_group store the strings passed in by the user for NFS params.
384      * nfs_uid and nfs_gid represent the converted/looked up ID numbers which are used
385      * during run time, and are not based on the configuration */
386     char *nfs_user;
387     char *nfs_group;
388     uid_t nfs_uid;
389     gid_t nfs_gid;
390 
391     /* We need a flag to remember that the threshold event for this source was
392      * registered with a full index (vda[3]) so that we can properly report just
393      * one event for it */
394     bool thresholdEventWithIndex;
395 };
396 
397 G_DEFINE_AUTOPTR_CLEANUP_FUNC(virStorageSource, virObjectUnref);
398 
399 void
400 virStorageAuthDefFree(virStorageAuthDef *def);
401 
402 virStorageAuthDef *
403 virStorageAuthDefCopy(const virStorageAuthDef *src);
404 
405 virStorageAuthDef *
406 virStorageAuthDefParse(xmlNodePtr node,
407                        xmlXPathContextPtr ctxt);
408 
409 void
410 virStorageAuthDefFormat(virBuffer *buf,
411                         virStorageAuthDef *authdef);
412 
413 void
414 virStoragePRDefFree(virStoragePRDef *prd);
415 
416 virStoragePRDef *
417 virStoragePRDefParseXML(xmlXPathContextPtr ctxt);
418 
419 void
420 virStoragePRDefFormat(virBuffer *buf,
421                       virStoragePRDef *prd,
422                       bool migratable);
423 
424 bool
425 virStoragePRDefIsEqual(virStoragePRDef *a,
426                        virStoragePRDef *b);
427 
428 bool
429 virStoragePRDefIsManaged(virStoragePRDef *prd);
430 
431 bool
432 virStorageSourceChainHasManagedPR(virStorageSource *src);
433 
434 void
435 virStorageSourceNVMeDefFree(virStorageSourceNVMeDef *def);
436 
437 G_DEFINE_AUTOPTR_CLEANUP_FUNC(virStorageSourceNVMeDef, virStorageSourceNVMeDefFree);
438 
439 bool
440 virStorageSourceChainHasNVMe(const virStorageSource *src);
441 
442 virSecurityDeviceLabelDef *
443 virStorageSourceGetSecurityLabelDef(virStorageSource *src,
444                                     const char *model);
445 
446 void
447 virStorageNetHostDefClear(virStorageNetHostDef *def);
448 
449 void
450 virStorageNetHostDefFree(size_t nhosts,
451                          virStorageNetHostDef *hosts);
452 
453 virStorageNetHostDef *
454 virStorageNetHostDefCopy(size_t nhosts,
455                          virStorageNetHostDef *hosts);
456 
457 int
458 virStorageSourceInitChainElement(virStorageSource *newelem,
459                                  virStorageSource *old,
460                                  bool force);
461 
462 void
463 virStorageSourcePoolDefFree(virStorageSourcePoolDef *def);
464 
465 void
466 virStorageSourceClear(virStorageSource *def);
467 
468 int
469 virStorageSourceGetActualType(const virStorageSource *def);
470 
471 bool
472 virStorageSourceIsLocalStorage(const virStorageSource *src);
473 
474 bool
475 virStorageSourceIsEmpty(virStorageSource *src);
476 
477 bool
478 virStorageSourceIsBlockLocal(const virStorageSource *src);
479 
480 virStorageSource *
481 virStorageSourceNew(void);
482 
483 void
484 virStorageSourceBackingStoreClear(virStorageSource *def);
485 
486 int
487 virStorageSourceNetCookiesValidate(virStorageSource *src);
488 
489 virStorageSource *
490 virStorageSourceCopy(const virStorageSource *src,
491                      bool backingChain)
492     ATTRIBUTE_NONNULL(1);
493 
494 bool
495 virStorageSourceIsSameLocation(virStorageSource *a,
496                                virStorageSource *b)
497     ATTRIBUTE_NONNULL(1) ATTRIBUTE_NONNULL(2);
498 
499 bool
500 virStorageSourceIsRelative(virStorageSource *src);
501 
502 void
503 virStorageSourceNetworkAssignDefaultPorts(virStorageSource *src)
504     ATTRIBUTE_NONNULL(1);
505 
506 bool
507 virStorageSourceIsBacking(const virStorageSource *src);
508 
509 bool
510 virStorageSourceHasBacking(const virStorageSource *src);
511 
512 int
513 virStorageSourcePrivateDataParseRelPath(xmlXPathContextPtr ctxt,
514                                         virStorageSource *src);
515 
516 int
517 virStorageSourcePrivateDataFormatRelPath(virStorageSource *src,
518                                          virBuffer *buf);
519 
520 void
521 virStorageSourceInitiatorParseXML(xmlXPathContextPtr ctxt,
522                                   virStorageSourceInitiatorDef *initiator);
523 
524 void
525 virStorageSourceInitiatorFormatXML(virStorageSourceInitiatorDef *initiator,
526                                    virBuffer *buf);
527 
528 int
529 virStorageSourceInitiatorCopy(virStorageSourceInitiatorDef *dest,
530                               const virStorageSourceInitiatorDef *src);
531 
532 void
533 virStorageSourceInitiatorClear(virStorageSourceInitiatorDef *initiator);
534 
535 G_DEFINE_AUTOPTR_CLEANUP_FUNC(virStorageAuthDef, virStorageAuthDefFree);
536