File: formatstorage.html

package info (click to toggle)
libvirt 5.6.0-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 240,844 kB
  • sloc: ansic: 584,521; xml: 176,725; sh: 9,912; python: 4,731; perl: 4,343; makefile: 3,321; ml: 465
file content (1171 lines) | stat: -rw-r--r-- 54,002 bytes parent folder | download | duplicates (2)
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
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <!--
        This file is autogenerated from formatstorage.html.in
        Do not edit this file. Changes will be lost.
      -->
  <!--
        This page was generated at Tue Jul 30 02:04:26 UTC 2019.
      -->
  <head>
    <meta charset="UTF-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1"/>
    <link rel="stylesheet" type="text/css" href="main.css"/>
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png"/>
    <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png"/>
    <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png"/>
    <link rel="manifest" href="/manifest.json"/>
    <meta name="theme-color" content="#ffffff"/>
    <title>libvirt: Storage pool and volume XML format</title>
    <meta name="description" content="libvirt, virtualization, virtualization API"/>
    <script type="text/javascript" src="js/main.js">
      <!--// forces non-empty element-->
    </script>
  </head>
  <body onload="pageload()">
    <div id="body">
      <div id="content">
        <h1>Storage pool and volume XML format</h1>
        <ul>
          <li>
            <a href="#StoragePool">Storage pool XML</a>
            <ul>
              <li>
                <a href="#StoragePoolFirst">General metadata</a>
              </li>
              <li>
                <a href="#StoragePoolSource">Source elements</a>
              </li>
              <li>
                <a href="#StoragePoolTarget">Target elements</a>
              </li>
              <li>
                <a href="#StoragePoolExtents">Device extents</a>
              </li>
              <li>
                <a href="#StoragePoolRefresh">Refresh overrides</a>
              </li>
              <li>
                <a href="#StoragePoolNamespaces">Storage Pool Namespaces</a>
              </li>
            </ul>
          </li>
          <li>
            <a href="#StorageVol">Storage volume XML</a>
            <ul>
              <li>
                <a href="#StorageVolFirst">General metadata</a>
              </li>
              <li>
                <a href="#StorageVolTarget">Target elements</a>
              </li>
              <li>
                <a href="#StorageVolBacking">Backing store elements</a>
              </li>
            </ul>
          </li>
          <li>
            <a href="#examples">Example configuration</a>
            <ul>
              <li>
                <a href="#exampleFile">File based storage pool</a>
              </li>
              <li>
                <a href="#exampleISCSI">iSCSI based storage pool</a>
              </li>
              <li>
                <a href="#exampleVol">Storage volume</a>
              </li>
              <li>
                <a href="#exampleLuks">Storage volume using LUKS</a>
              </li>
            </ul>
          </li>
        </ul>
        <h2>
          <a id="StoragePool">Storage pool XML</a>
          <a class="headerlink" href="#StoragePool" title="Permalink to this headline">¶</a>
        </h2>
        <p>
      Although all storage pool backends share the same public APIs and
      XML format, they have varying levels of capabilities. Some may
      allow creation of volumes, others may only allow use of pre-existing
      volumes. Some may have constraints on volume size, or placement.
    </p>
        <p>
      The top level tag for a storage pool document is 'pool'. It has
      a single attribute <code>type</code>, which is one of <code>dir</code>,
      <code>fs</code>, <code>netfs</code>, <code>disk</code>,
      <code>iscsi</code>, <code>logical</code>, <code>scsi</code>
      (all <span class="since">since 0.4.1</span>),
      <code>mpath</code> (<span class="since">since 0.7.1</span>),
      <code>rbd</code> (<span class="since">since 0.9.13</span>),
      <code>sheepdog</code> (<span class="since">since 0.10.0</span>),
      <code>gluster</code> (<span class="since">since 1.2.0</span>),
      <code>zfs</code> (<span class="since">since 1.2.8</span>),
      <code>vstorage</code> (<span class="since">since 3.1.0</span>),
      or <code>iscsi-direct</code> (<span class="since">since 4.7.0</span>).
      This corresponds to the
      storage backend drivers listed further along in this document.
    </p>
        <h3>
          <a id="StoragePoolFirst">General metadata</a>
          <a class="headerlink" href="#StoragePoolFirst" title="Permalink to this headline">¶</a>
        </h3>
        <pre>
&lt;pool type="iscsi"&gt;
  &lt;name&gt;virtimages&lt;/name&gt;
  &lt;uuid&gt;3e3fce45-4f53-4fa7-bb32-11f34168b82b&lt;/uuid&gt;
  &lt;allocation&gt;10000000&lt;/allocation&gt;
  &lt;capacity&gt;50000000&lt;/capacity&gt;
  &lt;available&gt;40000000&lt;/available&gt;
  ...</pre>
        <dl>
          <dt>
            <code>name</code>
          </dt>
          <dd>Providing a name for the pool which is unique to the host.
        This is mandatory when defining a pool. <span class="since">Since 0.4.1</span></dd>
          <dt>
            <code>uuid</code>
          </dt>
          <dd>Providing an identifier for the pool which is globally unique.
        This is optional when defining a pool, a UUID will be generated if
        omitted. <span class="since">Since 0.4.1</span></dd>
          <dt>
            <code>allocation</code>
          </dt>
          <dd>Providing the total storage allocation for the pool. This may
        be larger than the sum of the allocation of all volumes due to
        metadata overhead. This value is in bytes. This is not applicable
        when creating a pool. <span class="since">Since 0.4.1</span></dd>
          <dt>
            <code>capacity</code>
          </dt>
          <dd>Providing the total storage capacity for the pool. Due to
        underlying device constraints it may not be possible to use the
        full capacity for storage volumes. This value is in bytes. This
        is not applicable when creating a pool. <span class="since">Since 0.4.1</span></dd>
          <dt>
            <code>available</code>
          </dt>
          <dd>Providing the free space available for allocating new volumes
        in the pool. Due to underlying device constraints it may not be
        possible to allocate the entire free space to a single volume.
        This value is in bytes. This is not applicable when creating a
        pool. <span class="since">Since 0.4.1</span></dd>
        </dl>
        <h3>
          <a id="StoragePoolSource">Source elements</a>
          <a class="headerlink" href="#StoragePoolSource" title="Permalink to this headline">¶</a>
        </h3>
        <p>
      A single <code>source</code> element is contained within the top level
      <code>pool</code> element. This tag is used to describe the source of
      the storage pool. The set of child elements that it will contain
      depend on the pool type, but come from the following child elements:
    </p>
        <pre>
...
&lt;source&gt;
  &lt;host name="iscsi.example.com"/&gt;
  &lt;device path="iqn.2013-06.com.example:iscsi-pool"/&gt;
  &lt;auth type='chap' username='myname'&gt;
    &lt;secret usage='mycluster_myname'/&gt;
  &lt;/auth&gt;
  &lt;vendor name="Acme"/&gt;
  &lt;product name="model"/&gt;
&lt;/source&gt;
...</pre>
        <pre>
...
&lt;source&gt;
  &lt;device path='/dev/mapper/mpatha' part_separator='no'/&gt;
  &lt;format type='gpt'/&gt;
&lt;/source&gt;
...</pre>
        <pre>
...
&lt;source&gt;
  &lt;adapter type='scsi_host' name='scsi_host1'/&gt;
&lt;/source&gt;
...</pre>
        <pre>
...
&lt;source&gt;
  &lt;adapter type='scsi_host'&gt;
    &lt;parentaddr unique_id='1'&gt;
      &lt;address domain='0x0000' bus='0x00' slot='0x1f' addr='0x2'/&gt;
    &lt;/parentaddr&gt;
  &lt;/adapter&gt;
&lt;/source&gt;
...</pre>
        <pre>
...
&lt;source&gt;
  &lt;adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/&gt;
&lt;/source&gt;
...</pre>
        <pre>
...
  &lt;source&gt;
    &lt;host name='localhost'/&gt;
    &lt;dir path='/var/lib/libvirt/images'/&gt;
    &lt;format type='nfs'/&gt;
    &lt;protocol ver='3'/&gt;
  &lt;/source&gt;
...</pre>
        <dl>
          <dt>
            <code>device</code>
          </dt>
          <dd>Provides the source for pools backed by physical devices
        (pool types <code>fs</code>, <code>logical</code>, <code>disk</code>,
        <code>iscsi</code>, <code>iscsi-direct</code>, <code>zfs</code>,
        <code>vstorage</code>).
        May be repeated multiple times depending on backend driver. Contains
        a required attribute <code>path</code> which is either the fully
        qualified path to the block device node or for <code>iscsi</code>
        or <code>iscsi-direct</code> the iSCSI Qualified Name (IQN).
        <span class="since">Since 0.4.1</span>
        <p>An optional attribute <code>part_separator</code> for each
        <code>path</code> may be supplied. Valid values for the attribute
        may be either "yes" or "no". This attribute is to be used for a
        <code>disk</code> pool type using a <code>path</code> to a
        device mapper multipath device. Setting the attribute to "yes"
        causes libvirt to attempt to generate and find target volume path's
        using a "p" separator. The default algorithm used by device mapper
        is to add the "p" separator only when the source device path ends
        with a number; however, it's possible to configure the devmapper
        device to not use 'user_friendly_names' thus creating partitions
        with the "p" separator even when the device source path does not
        end with a number.
        <span class="since">Since 1.3.1</span></p></dd>
          <dt>
            <code>dir</code>
          </dt>
          <dd>Provides the source for pools backed by directories (pool
        types <code>dir</code>, <code>netfs</code>, <code>gluster</code>),
        or optionally to select a subdirectory
        within a pool that resembles a filesystem (pool
        type <code>gluster</code>). May
        only occur once. Contains a single attribute <code>path</code>
        which is the fully qualified path to the backing directory or
        for a <code>netfs</code> pool type using <code>format</code>
        type "cifs", the path to the Samba share without the leading slash.
        <span class="since">Since 0.4.1</span></dd>
          <dt>
            <code>adapter</code>
          </dt>
          <dd>Provides the source for pools backed by SCSI adapters (pool
        type <code>scsi</code>). May only occur once.
        <dl><dt><code>name</code></dt><dd>The SCSI adapter name (e.g. "scsi_host1", although a name
            such as "host1" is still supported for backwards compatibility,
            it is not recommended). The scsi_host name to be used can be
            determined from the output of a <code>virsh nodedev-list
            scsi_host</code> command followed by a combination of
            <code>lspci</code> and <code>virsh nodedev-dumpxml
            scsi_hostN</code> commands to find the <code>scsi_hostN</code>
            to be used. <span class="since">Since 0.6.2</span>
            <p>
            It is further recommended to utilize the
            <code>parentaddr</code> element since it's possible to have
            the path to which the scsi_hostN uses change between system
            reboots. <span class="since">Since 1.2.7</span>
            </p>
          </dd></dl>
        <dl><dt><code>type</code></dt><dd>Specifies the adapter type. Valid values are "scsi_host" or
            "fc_host". If omitted and the <code>name</code> attribute is
            specified, then it defaults to "scsi_host". To keep backwards
            compatibility, this attribute is optional <b>only</b> for the
            "scsi_host" adapter, but is mandatory for the "fc_host" adapter.
            <span class="since">Since 1.0.5</span>
            A "fc_host" capable scsi_hostN can be determined by using
            <code>virsh nodedev-list --cap fc_host</code>.
            <span class="since">Since 1.2.8</span>
            <p>
            Note: Regardless of whether a "scsi_host" adapter type is defined
            using a <code>name</code> or a <code>parentaddr</code>, it
            should refer to a real scsi_host adapter as found through a
            <code>virsh nodedev-list scsi_host</code> and <code>virsh
            nodedev-dumpxml scsi_hostN</code> on one of the scsi_host's
            displayed. It should not refer to a "fc_host" capable scsi_hostN
            nor should it refer to the vHBA created for some "fc_host"
            adapter. For a vHBA the <code>nodedev-dumpxml</code>
            output parent setting will be the "fc_host" capable scsi_hostN
            value. Additionally, do not refer to an iSCSI scsi_hostN for the
            "scsi_host" source. An iSCSI scsi_hostN's
            <code>nodedev-dumpxml</code> output parent field is generally
            "computer". This is a libvirt created parent value indicating
            no parent was defined for the node device.
            </p>
            </dd></dl>
        <dl><dt><code>wwnn</code> and <code>wwpn</code></dt><dd>The required "World Wide Node Name" (<code>wwnn</code>) and
            "World Wide Port Name" (<code>wwpn</code>) are used by the
            "fc_host" adapter to uniquely identify the vHBA device in the
            Fibre Channel storage fabric. If the vHBA device already exists
            as a Node Device, then libvirt will use it; otherwise, the vHBA
            will be created using the provided values. It is considered a
            configuration error use the values from the HBA as those would
            be for a "scsi_host" <code>type</code> pool instead. The
            <code>wwnn</code> and <code>wwpn</code> have very specific
            format requirements based on the hypervisor being used, thus
            care should be taken if you decide to generate your own to
            follow the standards; otherwise, the pool will fail to start
            with an opaque error message indicating failure to write to
            the vport_create file during vport create/delete due to
            "No such file or directory".
            <span class="since">Since 1.0.4</span>
          </dd></dl>
        <dl><dt><code>parent</code></dt><dd>Used by the "fc_host" adapter type to optionally specify the
            parent scsi_host device defined in the
            <a href="formatnode.html">Node Device</a> database as the
            <a href="http://wiki.libvirt.org/page/NPIV_in_libvirt">NPIV</a>
            virtual Host Bus Adapter (vHBA). The value provided must be
            a vport capable scsi_host. The value is not the scsi_host of
            the vHBA created by 'virsh nodedev-create', rather it is
            the parent of that vHBA. If the value is not provided, libvirt
            will determine the parent based either finding the wwnn,wwpn
            defined for an existing scsi_host or by creating a vHBA. Providing
            the parent attribute is also useful for the duplicate pool
            definition checks. This is more important in environments where
            both the "fc_host" and "scsi_host" source adapter pools are being
            used in order to ensure a new definition doesn't duplicate using
            the scsi_hostN of some existing storage pool.
            <span class="since">Since 1.0.4</span>
          </dd><dt><code>parent_wwnn</code> and <code>parent_wwpn</code></dt><dd>Instead of the <code>parent</code> to specify which scsi_host
            to use by name, it's possible to provide the wwnn and wwpn of
            the parent to be used for the vHBA in order to ensure that
            between reboots or after a hardware configuration change that
            the scsi_host parent name doesn't change. Both the parent_wwnn
            and parent_wwpn must be provided.
            <span class="since">Since 3.0.0</span>
          </dd><dt><code>parent_fabric_wwn</code></dt><dd>Instead of the <code>parent</code> to specify which scsi_host
            to use by name, it's possible to provide the fabric_wwn on which
            the scsi_host exists. This provides flexibility for choosing
            a scsi_host that may be available on the fabric rather than
            requiring a specific parent by wwnn or wwpn to be available.
            <span class="since">Since 3.0.0</span>
          </dd><dt><code>managed</code></dt><dd>An optional attribute to instruct the SCSI storage backend to
            manage destroying the vHBA when the pool is destroyed. For
            configurations that do not provide an already created vHBA
            from a 'virsh nodedev-create', libvirt will set this property
            to "yes". For configurations that have already created a vHBA
            via 'virsh nodedev-create' and are using the wwnn/wwpn from
            that vHBA and optionally the scsi_host parent, setting this
            attribute to "yes" will allow libvirt to destroy the node device
            when the pool is destroyed. If this attribute is set to "no" or
            not defined in the XML, then libvirt will not destroy the vHBA.
            <span class="since">Since 1.2.11</span>
          </dd></dl>
        <dl><dt><code>parentaddr</code></dt><dd>Used by the "scsi_host" adapter type instead of the
            <code>name</code> attribute to more uniquely identify the
            SCSI host. Using a combination of the <code>unique_id</code>
            attribute and the <code>address</code> element to formulate
            a PCI address, a search will be performed of the
            <code>/sys/class/scsi_host/hostNN</code> links for a
            matching PCI address with a matching <code>unique_id</code>
            value in the <code>/sys/class/scsi_host/hostNN/unique_id</code>
            file. The value in the "unique_id" file will be unique enough
            for the specific PCI address. The <code>hostNN</code> will be
            used by libvirt as the basis to define which SCSI host is to
            be used for the currently booted system.
            <span class="since">Since 1.2.7</span>
            <dl><dt><code>address</code></dt><dd>The PCI address of the scsi_host device to be used. Using
                a PCI address provides consistent naming across system reboots
                and kernel reloads. The address will have four attributes:
                <code>domain</code> (a 2-byte hex integer, not currently used
                by qemu), <code>bus</code> (a hex value between 0 and 0xff,
                inclusive), <code>slot</code> (a hex value between 0x0 and
                0x1f, inclusive), and <code>function</code> (a value between
                0 and 7, inclusive). The PCI address can be determined by
                listing the <code>/sys/bus/pci/devices</code> and the
                <code>/sys/class/scsi_host</code> directories in order to
                find the expected scsi_host device. The address will be
                provided in a format such as "0000:00:1f:2" which can be
                used to generate the expected PCI address
                "domain='0x0000' bus='0x00' slot='0x1f' function='0x0'".
                Optionally, using the combination of the commands 'virsh
                nodedev-list scsi_host' and 'virsh nodedev-dumpxml' for a
                specific list entry and converting the resulting
                <code>path</code> element as the basis to formulate the
                correctly formatted PCI address.
              </dd></dl>
            <dl><dt><code>unique_id</code></dt><dd>Required <code>parentaddr</code> attribute used to determine
                which of the scsi_host adapters for the provided PCI address
                should be used. The value is determine by contents of the
                <code>unique_id</code> file for the specific scsi_host adapter.
                For a PCI address of "0000:00:1f:2", the unique identifer files
                can be found using the command
                <code>find -H /sys/class/scsi_host/host*/unique_id |
                xargs grep '[0-9]'</code>. Optionally, the
                <code>virsh nodedev-dumpxml scsi_hostN</code>' of a
                specific scsi_hostN list entry will list the
                <code>unique_id</code> value.
              </dd></dl>
          </dd></dl>
      </dd>
          <dt>
            <code>host</code>
          </dt>
          <dd>Provides the source for pools backed by storage from a
        remote server (pool types <code>netfs</code>, <code>iscsi</code>,
        <code>iscsi-direct</code>,
        <code>rbd</code>, <code>sheepdog</code>, <code>gluster</code>). Will be
        used in combination with a <code>directory</code>
        or <code>device</code> element. Contains an attribute <code>name</code>
        which is the hostname or IP address of the server. May optionally
        contain a <code>port</code> attribute for the protocol specific
        port number. Duplicate storage pool definition checks may perform
        a cursory check that the same host name by string comparison in the
        new pool does not match an existing pool's source host name when
        combined with the <code>directory</code> or <code>device</code>
        element. Name resolution of the provided hostname or IP address
        is left to the storage driver backend interactions with the remote
        server. See the <a href="storage.html">storage driver page</a> for
        any restrictions for specific storage backends.
        <span class="since">Since 0.4.1</span></dd>
          <dt>
            <code>initiator</code>
          </dt>
          <dd>Required by the <code>iscsi-direct</code> pool in order to provide
        the iSCSI Qualified Name (IQN) to communicate with the pool's
        <code>device</code> target IQN. There is one sub-element
        <code>iqn</code> with the <code>name</code> attribute to describe
        the IQN for the initiator.
        <span class="since">Since 4.7.0</span></dd>
          <dt>
            <code>auth</code>
          </dt>
          <dd>If present, the <code>auth</code> element provides the
        authentication credentials needed to access the source by the
        setting of the <code>type</code> attribute (pool
        types <code>iscsi</code>, <code>iscsi-direct</code>, <code>rbd</code>).
        The <code>type</code>
        must be either "chap" or "ceph". Use "ceph" for
        Ceph RBD (Rados Block Device) network sources and use "iscsi" for CHAP
        (Challenge-Handshake Authentication Protocol) iSCSI
        targets. Additionally a mandatory attribute
        <code>username</code> identifies the username to use during
        authentication as well as a sub-element <code>secret</code> with
        a mandatory attribute <code>type</code>, to tie back to a
        <a href="formatsecret.html">libvirt secret object</a> that
        holds the actual password or other credentials. The domain XML
        intentionally does not expose the password, only the reference
        to the object that manages the password.
        The <code>secret</code> element requires either a <code>uuid</code>
        attribute with the UUID of the secret object or a <code>usage</code>
        attribute matching the key that was specified in the
        secret object.  <span class="since">Since 0.9.7 for "ceph" and
        1.1.1 for "chap"</span>
      </dd>
          <dt>
            <code>name</code>
          </dt>
          <dd>Provides the source for pools backed by storage from a
        named element (pool types <code>logical</code>, <code>rbd</code>,
        <code>sheepdog</code>, <code>gluster</code>).  Contains a
        string identifier.
        <span class="since">Since 0.4.5</span></dd>
          <dt>
            <code>format</code>
          </dt>
          <dd>Provides information about the format of the pool (pool
        types <code>fs</code>, <code>netfs</code>, <code>disk</code>,
        <code>logical</code>). This
        contains a single attribute <code>type</code> whose value is
        backend specific. This is typically used to indicate filesystem
        type, or network filesystem type, or partition table type, or
        LVM metadata type. All drivers are required to have a default
        value for this, so it is optional. <span class="since">Since 0.4.1</span></dd>
          <dt>
            <code>protocol</code>
          </dt>
          <dd>For a <code>netfs</code> Storage Pool provide a mechanism to
        define which NFS protocol version number will be used to contact
        the server's NFS service. The attribute <code>ver</code> accepts
        an unsigned integer as the version number to use.
        <span class="since">Since 5.1.0</span></dd>
          <dt>
            <code>vendor</code>
          </dt>
          <dd>Provides optional information about the vendor of the
        storage device. This contains a single
        attribute <code>name</code> whose value is backend
        specific. <span class="since">Since 0.8.4</span></dd>
          <dt>
            <code>product</code>
          </dt>
          <dd>Provides an optional product name of the storage device.
        This contains a single attribute <code>name</code> whose value
        is backend specific.  <span class="since">Since 0.8.4</span></dd>
        </dl>
        <h3>
          <a id="StoragePoolTarget">Target elements</a>
          <a class="headerlink" href="#StoragePoolTarget" title="Permalink to this headline">¶</a>
        </h3>
        <p>
      A single <code>target</code> element is contained within the top level
      <code>pool</code> element for some types of pools (pool
      types <code>dir</code>, <code>fs</code>, <code>netfs</code>,
      <code>logical</code>, <code>disk</code>, <code>iscsi</code>,
      <code>scsi</code>, <code>mpath</code>, <code>zfs</code>).
      This tag is used to describe the mapping of
      the storage pool into the host filesystem. It can contain the following
      child elements:
    </p>
        <pre>
  ...
  &lt;target&gt;
    &lt;path&gt;/dev/disk/by-path&lt;/path&gt;
    &lt;permissions&gt;
      &lt;owner&gt;107&lt;/owner&gt;
      &lt;group&gt;107&lt;/group&gt;
      &lt;mode&gt;0744&lt;/mode&gt;
      &lt;label&gt;virt_image_t&lt;/label&gt;
    &lt;/permissions&gt;
  &lt;/target&gt;
&lt;/pool&gt;</pre>
        <dl>
          <dt>
            <code>path</code>
          </dt>
          <dd>Provides the location at which the pool will be mapped into
        the local filesystem namespace, as an absolute path. For a
        filesystem/directory based pool it will be a fully qualified name of
        the directory in which volumes will be created. For device based pools
        it will be a fully qualified name of the directory in which
        devices nodes exist. For the latter <code>/dev/</code> may seem
        like the logical choice, however, devices nodes there are not
        guaranteed stable across reboots, since they are allocated on
        demand. It is preferable to use a stable location such as one
        of the <code>/dev/disk/by-{path|id|uuid|label}</code> locations.
        For <code>logical</code> and <code>zfs</code> pool types, a
        provided value is ignored and a default path generated.
        For a Multipath pool (type <code>mpath</code>), the provided
        value is ignored and the default value of "/dev/mapper" is used.
        <span class="since">Since 0.4.1</span>
      </dd>
          <dt>
            <code>permissions</code>
          </dt>
          <dd>This is currently only useful for directory or filesystem based
        pools, which are mapped as a directory into the local filesystem
        namespace. It provides information about the permissions to use for the
        final directory when the pool is built. There are 4 child elements.
        The <code>mode</code> element contains the octal permission set.
        The <code>mode</code> defaults to 0711 when not provided.
        The <code>owner</code> element contains the numeric user ID.
        The <code>group</code> element contains the numeric group ID.
        If <code>owner</code> or <code>group</code> aren't specified when
        creating a directory, the UID and GID of the libvirtd process are used.
        The <code>label</code> element contains the MAC (eg SELinux)
        label string.
        <span class="since">Since 0.4.1</span>
        For running directory or filesystem based pools, these fields
        will be filled with the values used by the existing directory.
        <span class="since">Since 1.2.16</span>
      </dd>
        </dl>
        <h3>
          <a id="StoragePoolExtents">Device extents</a>
          <a class="headerlink" href="#StoragePoolExtents" title="Permalink to this headline">¶</a>
        </h3>
        <p>
      If a storage pool exposes information about its underlying
      placement / allocation scheme, the <code>device</code> element
      within the <code>source</code> element may contain information
      about its available extents. Some pools have a constraint that
      a volume must be allocated entirely within a single constraint
      (eg disk partition pools). Thus the extent information allows an
      application to determine the maximum possible size for a new
      volume
    </p>
        <p>
      For storage pools supporting extent information, within each
      <code>device</code> element there will be zero or more <code>freeExtent</code>
      elements. Each of these elements contains two attributes, <code>start</code>
      and <code>end</code> which provide the boundaries of the extent on the
      device, measured in bytes.  <span class="since">Since 0.4.1</span>
    </p>
        <h3>
          <a id="StoragePoolRefresh">Refresh overrides</a>
          <a class="headerlink" href="#StoragePoolRefresh" title="Permalink to this headline">¶</a>
        </h3>
        <p>
      The optional <code>refresh</code> element can control how the pool and
      associated volumes are refreshed (pool type <code>rbd</code>). The
      <code>allocation</code> attribute of the <code>volume</code> child element
      controls the method used for computing the allocation of a volume. The
      valid attribute values are <code>default</code> to compute the actual
      usage or <code>capacity</code> to use the logical capacity for cases where
      computing the allocation is too expensive. The following XML snippet
      shows the syntax:
      <pre>
&lt;pool type="rbd"&gt;
  &lt;name&gt;myrbdpool&lt;/name&gt;
...
  &lt;source/&gt;
...
  &lt;refresh&gt;
    &lt;volume allocation='capacity'/&gt;
  &lt;/refresh&gt;
...
&lt;/pool&gt;
</pre>
      <span class="since">Since 5.2.0</span>
    </p>
        <h3>
          <a id="StoragePoolNamespaces">Storage Pool Namespaces</a>
          <a class="headerlink" href="#StoragePoolNamespaces" title="Permalink to this headline">¶</a>
        </h3>
        <p>
      Usage of Storage Pool Namespaces provides a mechanism to provide
      pool type specific data in a free form or arbitrary manner via
      XML syntax targeted solely for the needs of the specific pool type
      which is not otherwise supported in standard XML. For the "fs" and
      "netfs" pool types this provides a mechanism to provide additional
      mount options on the command line. For the "rbd" pool this provides
      a mechanism to override default settings for RBD configuration options.
    </p>
        <p>
      Usage of namespaces comes with no support guarantees. It is intended
      for developers testing out a concept prior to requesting an explicitly
      supported XML option in libvirt, and thus should never be used in
      production.
    </p>
        <dl>
          <dt>
            <code>fs:mount_opts</code>
          </dt>
          <dd>Provides an XML namespace mechanism to optionally utilize
        specifically named options for the mount command via the "-o"
        option for the <code>fs</code> or <code>netfs</code> type storage
        pools. In order to designate that the Storage Pool will be using
        the mechanism, the <code>pool</code> element must be modified to
        provide the XML namespace attribute syntax as follows:

        <p>
        xmlns:fs='http://libvirt.org/schemas/storagepool/fs/1.0'
        </p>

        <p>
        The <code>fs:mount_opts</code> defines the mount options by
        specifying multiple <code>fs:option</code> subelements with
        the attribute <code>name</code> specifying the mount option to
        be added. The value of the named option is not checked since
        it's possible options don't exist on all distributions. It is
        expected that proper and valid options will be supplied for the
        target host.
        </p>

        The following XML snippet shows the syntax required in order to
        utilize for a netfs pool:
      <pre>
&lt;pool type="netfs" xmlns:fs='http://libvirt.org/schemas/storagepool/fs/1.0'&gt;
  &lt;name&gt;nfsimages&lt;/name&gt;
...
  &lt;source&gt;
...
  &lt;/source&gt;
...
  &lt;target&gt;
...
  &lt;/target&gt;
  &lt;fs:mount_opts&gt;
    &lt;fs:option name='sync'/&gt;
    &lt;fs:option name='lazytime'/&gt;
  &lt;/fs:mount_opts&gt;
&lt;/pool&gt;
...</pre>

      <span class="since">Since 5.1.0.</span></dd>
          <dt>
            <code>rbd:config_opts</code>
          </dt>
          <dd>Provides an XML namespace mechanism to optionally utilize
        specifically named options for the RBD configuration options
        via the rados_conf_set API for the <code>rbd</code> type
        storage pools. In order to designate that the Storage Pool
        will be using the mechanism, the <code>pool</code> element
        must be modified to provide the XML namespace attribute
        syntax as follows:

        <p>
        xmlns:rbd='http://libvirt.org/schemas/storagepool/rbd/1.0'
        </p>

        <p>
        The <code>rbd:config_opts</code> defines the configuration options
        by specifying multiple <code>rbd:option</code> subelements with
        the attribute <code>name</code> specifying the configuration option
        to be added and <code>value</code> specifying the configuration
        option value. The name and value for each option is only checked
        to be not empty. The name and value provided are not checked since
        it's possible options don't exist on all distributions. It is
        expected that proper and valid options will be supplied for the
        target host.
        </p>

        The following XML snippet shows the syntax required in order to
        utilize
      <pre>
&lt;pool type="rbd" xmlns:rbd='http://libvirt.org/schemas/storagepool/rbd/1.0'&gt;
  &lt;name&gt;myrbdpool&lt;/name&gt;
...
  &lt;source&gt;
...
  &lt;/source&gt;
...
  &lt;target&gt;
...
  &lt;/target&gt;
...
  &lt;rbd:config_opts&gt;
    &lt;rbd:option name='client_mount_timeout' value='45'/&gt;
    &lt;rbd:option name='rados_mon_op_timeout' value='20'/&gt;
    &lt;rbd:option name='rados_osd_op_timeout' value='10'/&gt;
  &lt;/rbd:config_opts&gt;
&lt;/pool&gt;
</pre>

      <span class="since">Since 5.1.0.</span></dd>
        </dl>
        <h2>
          <a id="StorageVol">Storage volume XML</a>
          <a class="headerlink" href="#StorageVol" title="Permalink to this headline">¶</a>
        </h2>
        <p>
      A storage volume will generally be either a file or a device
      node; <span class="since">since 1.2.0</span>, an optional
      output-only attribute <code>type</code> lists the actual type
      (file, block, dir, network, netdir or ploop), which is also available
      from <code>virStorageVolGetInfo()</code>.  The storage volume
      XML format is available <span class="since">since 0.4.1</span>
    </p>
        <h3>
          <a id="StorageVolFirst">General metadata</a>
          <a class="headerlink" href="#StorageVolFirst" title="Permalink to this headline">¶</a>
        </h3>
        <pre>
&lt;volume type='file'&gt;
  &lt;name&gt;sparse.img&lt;/name&gt;
  &lt;key&gt;/var/lib/xen/images/sparse.img&lt;/key&gt;
  &lt;allocation&gt;0&lt;/allocation&gt;
  &lt;capacity unit="T"&gt;1&lt;/capacity&gt;
  ...</pre>
        <dl>
          <dt>
            <code>name</code>
          </dt>
          <dd>Providing a name for the volume which is unique to the pool.
        This is mandatory when defining a volume. For a disk pool, the
        name must be combination of the <code>source</code> device path
        device and next partition number to be created. For example, if
        the <code>source</code> device path is /dev/sdb and there are no
        partitions on the disk, then the name must be sdb1 with the next
        name being sdb2 and so on.
        <span class="since">Since 0.4.1</span></dd>
          <dt>
            <code>key</code>
          </dt>
          <dd>Providing an identifier for the volume which identifies a
          single volume. In some cases it's possible to have two distinct keys
          identifying a single volume. This field cannot be set when creating
          a volume: it is always generated.
        <span class="since">Since 0.4.1</span></dd>
          <dt>
            <code>allocation</code>
          </dt>
          <dd>Providing the total storage allocation for the volume. This
        may be smaller than the logical capacity if the volume is sparsely
        allocated. It may also be larger than the logical capacity if the
        volume has substantial metadata overhead. This value is in bytes.
        If omitted when creating a volume, the volume will be fully
        allocated at time of creation. If set to a value smaller than the
        capacity, the pool has the <strong>option</strong> of deciding
        to sparsely allocate a volume. It does not have to honour requests
        for sparse allocation though. Different types of pools may treat
        sparse volumes differently. For example, the <code>logical</code>
        pool will not automatically expand volume's allocation when it
        gets full; the user is responsible for doing that or configuring
        dmeventd to do so automatically.<br/>
        <br/>
        By default this is specified in bytes, but an optional attribute
        <code>unit</code> can be specified to adjust the passed value.
        Values can be: 'B' or 'bytes' for bytes, 'KB' (kilobytes,
        10<sup>3</sup> or 1000 bytes), 'K' or 'KiB' (kibibytes,
        2<sup>10</sup> or 1024 bytes), 'MB' (megabytes, 10<sup>6</sup>
        or 1,000,000 bytes), 'M' or 'MiB' (mebibytes, 2<sup>20</sup>
        or 1,048,576 bytes), 'GB' (gigabytes, 10<sup>9</sup> or
        1,000,000,000 bytes), 'G' or 'GiB' (gibibytes, 2<sup>30</sup>
        or 1,073,741,824 bytes), 'TB' (terabytes, 10<sup>12</sup> or
        1,000,000,000,000 bytes), 'T' or 'TiB' (tebibytes,
        2<sup>40</sup> or 1,099,511,627,776 bytes), 'PB' (petabytes,
        10<sup>15</sup> or 1,000,000,000,000,000 bytes), 'P' or 'PiB'
        (pebibytes, 2<sup>50</sup> or 1,125,899,906,842,624 bytes),
        'EB' (exabytes, 10<sup>18</sup> or 1,000,000,000,000,000,000
        bytes), or 'E' or 'EiB' (exbibytes, 2<sup>60</sup> or
        1,152,921,504,606,846,976 bytes).  <span class="since">Since
        0.4.1, multi-character <code>unit</code> since
        0.9.11</span></dd>
          <dt>
            <code>capacity</code>
          </dt>
          <dd>Providing the logical capacity for the volume. This value is
        in bytes by default, but a <code>unit</code> attribute can be
        specified with the same semantics as for <code>allocation</code>
        This is compulsory when creating a volume.
        <span class="since">Since 0.4.1</span></dd>
          <dt>
            <code>physical</code>
          </dt>
          <dd>This output only element provides the host physical size of
        the target storage volume. The default output <code>unit</code>
        will be in bytes.
        <span class="since">Since 3.0.0</span></dd>
          <dt>
            <code>source</code>
          </dt>
          <dd>Provides information about the underlying storage allocation
        of the volume. This may not be available for some pool types.
        <span class="since">Since 0.4.1</span></dd>
          <dt>
            <code>target</code>
          </dt>
          <dd>Provides information about the representation of the volume
        on the local host. <span class="since">Since 0.4.1</span></dd>
        </dl>
        <h3>
          <a id="StorageVolTarget">Target elements</a>
          <a class="headerlink" href="#StorageVolTarget" title="Permalink to this headline">¶</a>
        </h3>
        <p>
      A single <code>target</code> element is contained within the top level
      <code>volume</code> element. This tag is used to describe the mapping of
      the storage volume into the host filesystem. It can contain the following
      child elements:
    </p>
        <pre>
...
&lt;target&gt;
  &lt;path&gt;/var/lib/virt/images/sparse.img&lt;/path&gt;
  &lt;format type='qcow2'/&gt;
  &lt;permissions&gt;
    &lt;owner&gt;107&lt;/owner&gt;
    &lt;group&gt;107&lt;/group&gt;
    &lt;mode&gt;0744&lt;/mode&gt;
    &lt;label&gt;virt_image_t&lt;/label&gt;
  &lt;/permissions&gt;
  &lt;timestamps&gt;
    &lt;atime&gt;1341933637.273190990&lt;/atime&gt;
    &lt;mtime&gt;1341930622.047245868&lt;/mtime&gt;
    &lt;ctime&gt;1341930622.047245868&lt;/ctime&gt;
  &lt;/timestamps&gt;
  &lt;encryption type='...'&gt;
    ...
  &lt;/encryption&gt;
  &lt;compat&gt;1.1&lt;/compat&gt;
  &lt;nocow/&gt;
  &lt;features&gt;
    &lt;lazy_refcounts/&gt;
  &lt;/features&gt;
&lt;/target&gt;</pre>
        <dl>
          <dt>
            <code>path</code>
          </dt>
          <dd>Provides the location at which the volume can be accessed on
        the local filesystem, as an absolute path. This is a readonly
        attribute, so shouldn't be specified when creating a volume.
        <span class="since">Since 0.4.1</span></dd>
          <dt>
            <code>format</code>
          </dt>
          <dd>Provides information about the pool specific volume format.
        For disk pools it will provide the partition table format type, but is
        not preserved after a pool refresh or libvirtd restart. Use extended
        in order to create an extended disk extent partition. For filesystem
        or directory pools it will provide the file format type, eg cow,
        qcow, vmdk, raw. If omitted when creating a volume, the pool's
        default format will be used. The actual format is specified via
        the <code>type</code> attribute. Consult the
        <a href="storage.html">storage driver page</a> for the list of valid
        volume format type values for each specific pool. The
        <code>format</code> will be ignored on input for pools without a
        volume format type value and the default pool format will be used.
        <span class="since">Since 0.4.1</span></dd>
          <dt>
            <code>permissions</code>
          </dt>
          <dd>Provides information about the permissions to use
        when creating volumes. This is currently only useful for directory
        or filesystem based pools, where the volumes allocated are simple
        files. For pools where the volumes are device nodes, the hotplug
        scripts determine permissions. There are 4 child elements.
        The <code>mode</code> element contains the octal permission set.
        The <code>mode</code> defaults to 0600 when not provided.
        The <code>owner</code> element contains the numeric user ID.
        The <code>group</code> element contains the numeric group ID.
        If <code>owner</code> or <code>group</code> aren't specified when
        creating a supported volume, the UID and GID of the libvirtd process
        are used. The <code>label</code> element contains the MAC (eg SELinux)
        label string.
        For existing directory or filesystem based volumes, these fields
        will be filled with the values used by the existing file.
        <span class="since">Since 0.4.1</span>
      </dd>
          <dt>
            <code>timestamps</code>
          </dt>
          <dd>Provides timing information about the volume. Up to four
        sub-elements are present,
        where <code>atime</code>, <code>btime</code>, <code>ctime</code>
        and <code>mtime</code> hold the access, birth, change and
        modification time of the volume, where known. The used time
        format is &lt;seconds&gt;.&lt;nanoseconds&gt; since the
        beginning of the epoch (1 Jan 1970). If nanosecond resolution
        is 0 or otherwise unsupported by the host OS or filesystem,
        then the nanoseconds part is omitted.  This is a readonly
        attribute and is ignored when creating a volume.
        <span class="since">Since 0.10.0</span>
      </dd>
          <dt>
            <code>encryption</code>
          </dt>
          <dd>If present, specifies how the volume is encrypted.  See
        the <a href="formatstorageencryption.html">Storage Encryption</a> page
        for more information.
      </dd>
          <dt>
            <code>compat</code>
          </dt>
          <dd>Specify compatibility level. So far, this is only used for
        <code>type='qcow2'</code> volumes. Valid values are <code>0.10</code>
        and <code>1.1</code> so far, specifying QEMU version the images should
        be compatible with. If the <code>feature</code> element is present,
        1.1 is used.
        <span class="since">Since 1.1.0</span> If omitted, 0.10 is used.
        <span class="since">Since 1.1.2</span>
      </dd>
          <dt>
            <code>nocow</code>
          </dt>
          <dd>Turn off COW of the newly created volume. So far, this is only valid
        for a file image in btrfs file system. It will improve performance when
        the file image is used in VM. To create non-raw file images, it
        requires QEMU version since 2.1. <span class="since">Since 1.2.7</span>
      </dd>
          <dt>
            <code>features</code>
          </dt>
          <dd>Format-specific features. Only used for <code>qcow2</code> now.
        Valid sub-elements are:
        <ul><li><code>&lt;lazy_refcounts/&gt;</code> - allow delayed reference
          counter updates. <span class="since">Since 1.1.0</span></li></ul>
      </dd>
        </dl>
        <h3>
          <a id="StorageVolBacking">Backing store elements</a>
          <a class="headerlink" href="#StorageVolBacking" title="Permalink to this headline">¶</a>
        </h3>
        <p>
      A single <code>backingStore</code> element is contained within the top level
      <code>volume</code> element. This tag is used to describe the optional copy
      on write, backing store for the storage volume. It can contain the following
      child elements:
    </p>
        <pre>
  ...
  &lt;backingStore&gt;
    &lt;path&gt;/var/lib/virt/images/master.img&lt;/path&gt;
    &lt;format type='raw'/&gt;
    &lt;permissions&gt;
      &lt;owner&gt;107&lt;/owner&gt;
      &lt;group&gt;107&lt;/group&gt;
      &lt;mode&gt;0744&lt;/mode&gt;
      &lt;label&gt;virt_image_t&lt;/label&gt;
    &lt;/permissions&gt;
  &lt;/backingStore&gt;
&lt;/volume&gt;</pre>
        <dl>
          <dt>
            <code>path</code>
          </dt>
          <dd>Provides the location at which the backing store can be accessed on
        the local filesystem, as an absolute path. If omitted, there is no
        backing store for this volume.
        <span class="since">Since 0.6.0</span></dd>
          <dt>
            <code>format</code>
          </dt>
          <dd>Provides information about the pool specific backing store format.
        For disk pools it will provide the partition type. For filesystem
        or directory pools it will provide the file format type, eg cow,
        qcow, vmdk, raw. The actual format is specified via the type attribute.
        Consult the pool-specific docs for the list of valid
        values. Most file formats require a backing store of the same format,
        however, the qcow2 format allows a different backing store format.
        <span class="since">Since 0.6.0</span></dd>
          <dt>
            <code>permissions</code>
          </dt>
          <dd>Provides information about the permissions of the backing file.
          See volume <code>permissions</code> documentation for explanation
          of individual fields.
        <span class="since">Since 0.6.0</span>
      </dd>
        </dl>
        <h2>
          <a id="examples">Example configuration</a>
          <a class="headerlink" href="#examples" title="Permalink to this headline">¶</a>
        </h2>
        <p>
      Here are a couple of examples, for a more complete set demonstrating
      every type of storage pool, consult the <a href="storage.html">storage driver page</a>
    </p>
        <h3>
          <a id="exampleFile">File based storage pool</a>
          <a class="headerlink" href="#exampleFile" title="Permalink to this headline">¶</a>
        </h3>
        <pre>
&lt;pool type="dir"&gt;
  &lt;name&gt;virtimages&lt;/name&gt;
  &lt;target&gt;
    &lt;path&gt;/var/lib/virt/images&lt;/path&gt;
  &lt;/target&gt;
&lt;/pool&gt;</pre>
        <h3>
          <a id="exampleISCSI">iSCSI based storage pool</a>
          <a class="headerlink" href="#exampleISCSI" title="Permalink to this headline">¶</a>
        </h3>
        <pre>
&lt;pool type="iscsi"&gt;
  &lt;name&gt;virtimages&lt;/name&gt;
  &lt;source&gt;
    &lt;host name="iscsi.example.com"/&gt;
    &lt;device path="iqn.2013-06.com.example:iscsi-pool"/&gt;
    &lt;auth type='chap' username='myuser'&gt;
      &lt;secret usage='libvirtiscsi'/&gt;
    &lt;/auth&gt;
  &lt;/source&gt;
  &lt;target&gt;
    &lt;path&gt;/dev/disk/by-path&lt;/path&gt;
  &lt;/target&gt;
&lt;/pool&gt;</pre>
        <h3>
          <a id="exampleVol">Storage volume</a>
          <a class="headerlink" href="#exampleVol" title="Permalink to this headline">¶</a>
        </h3>
        <pre>
&lt;volume&gt;
  &lt;name&gt;sparse.img&lt;/name&gt;
  &lt;allocation&gt;0&lt;/allocation&gt;
  &lt;capacity unit="T"&gt;1&lt;/capacity&gt;
  &lt;target&gt;
    &lt;path&gt;/var/lib/virt/images/sparse.img&lt;/path&gt;
    &lt;permissions&gt;
      &lt;owner&gt;107&lt;/owner&gt;
      &lt;group&gt;107&lt;/group&gt;
      &lt;mode&gt;0744&lt;/mode&gt;
      &lt;label&gt;virt_image_t&lt;/label&gt;
    &lt;/permissions&gt;
  &lt;/target&gt;
&lt;/volume&gt;</pre>
        <h3>
          <a id="exampleLuks">Storage volume using LUKS</a>
          <a class="headerlink" href="#exampleLuks" title="Permalink to this headline">¶</a>
        </h3>
        <pre>
&lt;volume&gt;
  &lt;name&gt;MyLuks.img&lt;/name&gt;
  &lt;capacity unit="G"&gt;5&lt;/capacity&gt;
  &lt;target&gt;
    &lt;path&gt;/var/lib/virt/images/MyLuks.img&lt;/path&gt;
    &lt;format type='raw'/&gt;
    &lt;encryption format='luks'&gt;
      &lt;secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/&gt;
    &lt;/encryption&gt;
  &lt;/target&gt;
&lt;/volume&gt;
    </pre>
      </div>
    </div>
    <div id="nav">
      <div id="home">
        <a href="index.html">Home</a>
      </div>
      <div id="jumplinks">
        <ul>
          <li>
            <a href="downloads.html">Download</a>
          </li>
          <li>
            <a href="contribute.html">Contribute</a>
          </li>
          <li>
            <a href="docs.html">Docs</a>
          </li>
        </ul>
      </div>
      <div id="search">
        <form id="simplesearch" action="https://www.google.com/search" enctype="application/x-www-form-urlencoded" method="get">
          <div>
            <input id="searchsite" name="sitesearch" type="hidden" value="libvirt.org"/>
            <input id="searchq" name="q" type="text" size="12" value=""/>
            <input name="submit" type="submit" value="Go"/>
          </div>
        </form>
        <div id="advancedsearch">
          <span>
            <input type="radio" name="what" id="whatwebsite" checked="checked" value="website"/>
            <label for="whatwebsite">Website</label>
          </span>
          <span>
            <input type="radio" name="what" id="whatwiki" value="wiki"/>
            <label for="whatwiki">Wiki</label>
          </span>
          <span>
            <input type="radio" name="what" id="whatdevs" value="devs"/>
            <label for="whatdevs">Developers list</label>
          </span>
          <span>
            <input type="radio" name="what" id="whatusers" value="users"/>
            <label for="whatusers">Users list</label>
          </span>
        </div>
      </div>
    </div>
    <div id="footer">
      <div id="contact">
        <h3>Contact</h3>
        <ul>
          <li>
            <a href="contact.html#email">email</a>
          </li>
          <li>
            <a href="contact.html#irc">irc</a>
          </li>
        </ul>
      </div>
      <div id="community">
        <h3>Community</h3>
        <ul>
          <li>
            <a href="https://twitter.com/hashtag/libvirt">twitter</a>
          </li>
          <li>
            <a href="http://stackoverflow.com/questions/tagged/libvirt">stackoverflow</a>
          </li>
          <li>
            <a href="http://serverfault.com/questions/tagged/libvirt">serverfault</a>
          </li>
        </ul>
      </div>
      <div id="conduct">
            Participants in the libvirt project agree to abide by <a href="governance.html#codeofconduct">the project code of conduct</a></div>
      <br class="clear"/>
    </div>
  </body>
</html>