1volume-request(4)                File Formats                volume-request(4)
2
3
4

NAME

6       volume-request,  volume-defaults - Solaris Volume Manager configuration
7       information for top down volume creation with metassist
8

SYNOPSIS

10       /usr/share/lib/xml/dtd/volume-request.dtd
11
12
13       /usr/share/lib/xml/dtd/volume-defaults.dtd
14
15
16       /etc/defaults/metassist.xml
17
18

DESCRIPTION

20       A volume  request  file,  XML-based  and  compliant  with  the  volume-
21       request.dtd  Document Type Definition, describes the characteristics of
22       the volumes that metassist should produce.
23
24
25       A system administrator would use the volume  request  file  instead  of
26       providing  options  at  the command line to give more specific instruc‐
27       tions about the characteristics of the  volumes  to  create.  A  volume
28       request  file  can request more than one volume, but all requested vol‐
29       umes must reside in the same disk set.
30
31
32       If you start metassist by providing a  volume-request  file  as  input,
33       metassist  can  implement  the configuration specified in the file, can
34       generate a command file that sets  up  the  configuraiton  for  you  to
35       inspect or edit, or can generate a volume configuration file for you to
36       inspect or edit.
37
38
39       As a system administrator, you would want to create  a  volume  request
40       file  if  you  need to reuse configurations (and do not want to reenter
41       the same command arguments), or if you prefer to  use  a  configuration
42       file to specify volume characteristics.
43
44
45       Volume  request files must be valid XML that complies with the document
46       type  definition   in   the   volume-request.dtd   file,   located   at
47       /usr/share/lib/xml/dtd/volume-request.dtd.  You create a volume request
48       file, and provide it as input to metassist to create volumes  from  the
49       top down.
50
51   Defining Volume Request
52       The  top  level  element  <volume-request> surrounds the volume request
53       data. This element has no attributes.  A  volume  request  requires  at
54       least  one  <diskset>  element,  which  must be the first element after
55       <volume-request>.
56
57
58       Optionally, the  <volume-request>  element  can  include  one  or  more
59       <available>  and <unavailable> elements to specify which controllers or
60       disks associated with a specific controller can or cannot  be  used  to
61       create the volume.
62
63
64       Optionally, the <volume-request> element can include a <hsp> element to
65       specify characteristics of a hot spare pool if fault recovery is used.
66
67
68       If not specified for a volume with fault-recovery, the first hot  spare
69       pool found in the disk set is used. If no hot spare pool exists but one
70       is required, a hot spare pool is created.
71
72
73       Optionally, the  volume-request  can  include  one  or  more  <concat>,
74       <stripe>, <mirror>, <volume> elements to specify volumes to create.
75
76   Defining Disk Set
77       Within  the  <volume-request>  element, a <diskset> element must exist.
78       The <diskset> element, with the name attribute, specifies the  name  of
79       the  disk  set  to be used. If this disk set does not exist, it is cre‐
80       ated. This element and the name attribute are required.
81
82   Defining Availability
83       Within the <volume-request> element and within other elements, you  can
84       specify  available or unavailable components (disks, or disks on a spe‐
85       cific controller path) for use or exclusion from use in a volume or hot
86       spare pool.
87
88
89       The  <available>  and  <unavailable>  elements require a name attribute
90       which specifies either a full ctd name, or a partial ctd name  that  is
91       used with the implied wildcard to complete the expression. For example,
92       specifying c3t2d0 as available would look like:
93
94         <available name="/dev/dsk/c3t2d0">
95
96
97
98       The <available> element also makes any unnamed components  unavailable.
99       Specifying all controllers exept c1 unavailable would look like:
100
101         <available name="c1">
102
103
104
105       Specifying all disks on controller 2 as unavailable would look like:
106
107         <unavailable name="c2">
108
109
110
111       The <unavailable> element can also be used to further restrict the list
112       of available components. For example, specifying all controllers  exept
113       c1 unavailable, and making all devices associated with c1t2 unavailable
114       as well would look like this:
115
116         <available name="c1">
117         <unavailable name="c1t2">
118
119
120
121       Components specified as available must be either part of the named disk
122       set  used  for  this  volume creation, or must be unused and not in any
123       disk set. If the components are selected for use, but are  not  in  the
124       specified diskset, the metassist command automatically adds them to the
125       diskset.
126
127
128       It is unnecessary to specify components that are in other disk sets  as
129       unavailable.  metassist automatically excludes them from consideration.
130       However, unused components or components that are  not  obviously  used
131       (for  example,  an unmounted slice that is reserved for different uses)
132       must be explicitly specified as unavailable, or the  metassist  command
133       can include them in the configuration.
134
135   Defining Hot Spare Pool
136       The  next  element  within  the  <volume-request>  element,  after  the
137       <diskset> and, optionally, <available> and <unavailable>  elements,  is
138       the  <hsp>  element.  Its  sole attribute specifies the name of the hot
139       spare pool:
140
141         <hsp name="hsp001">
142
143
144
145       The hot spare pool names must start with hsp and conclude with  a  num‐
146       ber,  thus following the existing Solaris Volume Manager hot spare pool
147       naming requirements.
148
149
150       Within the <hsp> element, you can specify one or more  <available>  and
151       <unavailable> elements to specify which disks, or disks associated with
152       a specific controller can or cannot be used to create  the  hot  spares
153       within the pool.
154
155
156       Also within the <hsp> element, you can use the <slice> element to spec‐
157       ify hot spares to be included in  the  hot  spare  pool  (see  DEFINING
158       SLICE).  Depending  on the requirements placed on the hot spare pool by
159       other parts of the volume request, additional slices can  be  added  to
160       the hot spare pool.
161
162   Defining Slice
163       The  <slice>  element  is  used  to define slices to include or exclude
164       within other elements. It requires only a name attribute to specify the
165       ctd  name  of  the slice, and the context of the <slice> element deter‐
166       mines the function of the element. Sample  slice  elements  might  look
167       like:
168
169         <slice name="c0t1d0s2" />
170         <slice name="c0t12938567201lkj29561sllkj381d0s2" />
171
172
173   Defining Stripe
174       The  <stripe> element defines stripes (interlaced RAID 0 volumes) to be
175       used in a volume. It can contain either slice elements  (to  explicitly
176       determine which slices are used), or appropriate combinations of avail‐
177       able and unavailable elements if the specific determination  of  slices
178       is to be left to the metassist command.
179
180
181       The  <stripe>  element  takes  an  optional name attribute to specify a
182       name. If the name is not specified, an available name is  automatically
183       selected  from  available  Solaris  Volume  Manager names. If possible,
184       names for related components are related.
185
186
187       The <stripe> element takes an optional size  attribute  that  specifies
188       the size as value and units (for example, 10TB, 5GB). If slices for the
189       <stripe> are explicitly specified, the size attribute is  ignored.  The
190       <available>  and <unavailable> elements can be used to constrain slices
191       for use in a stripe.
192
193
194       The <stripe> elements takes optional mincomp and maxcomp attributes  to
195       specify  both  the minimum and maximum number of components that can be
196       included in it. As with size, if slices for the <stripe> are explicitly
197       specified, the mincomp and maxcomp attributes are ignored.
198
199
200       The  <stripe>  elements  takes an optional interlace attribute as value
201       and units (for example, 16KB, 5BLOCKS, 20KB).  If  this  value  is  not
202       specified, the Solaris Volume Manager default value is used.
203
204
205       The <stripe> element takes an optional usehsp attribute to specify if a
206       hot spare pool should be associated with this component. This attribute
207       is  specified as a boolean value, as usehsp="TRUE". If the component is
208       not a submirror, this attribute is ignored.
209
210   Defining Concat
211       The <concat> element defines concats (non-interlaced RAID 0 volumes) to
212       be  used  in  a  configuration.  It  is  specified in the same way as a
213       <stripe> element, except  that  the  mincomp,  maxcomp,  and  interlace
214       attributes are not valid.
215
216   Defining Mirror
217       The  <mirror>  element defines mirrors (RAID 1 volumes) to be used in a
218       volume configuration. It  can  contain  combinations  of  <concat>  and
219       <stripe>  elements  (to  explicitly determine which volumes are used as
220       submirrors). Alternatively, it can have  a  size  attribute  specified,
221       along  with  the  appropriate combinations of available and unavailable
222       elements to leave the  specific  determination  of  components  to  the
223       metassist command.
224
225
226       The  <mirror>  element  takes  an  optional name attribute to specify a
227       name. If the name is not specified, an available name is  automatically
228       selected.
229
230
231       The  <mirror>  element  takes an optional size attribute that specifies
232       the size as value and units (for example, 10TB, 5GB). If  <stripe>  and
233       <concat>  elements  for the mirror are not specified, this attribute is
234       required. Otherwise, it is ignored.
235
236
237       The <mirror> element takes an optional nsubmirrors attribute to  define
238       the  number  of  submirrors  (1-4) to include. Like the size attribute,
239       this attribute is ignored if the underlying <concat> and <stripe>  sub‐
240       mirrors  are  explicitly  specified.  The  <mirror>  element  takes  an
241       optional read attribute to define the mirror read options  (ROUNDROBIN,
242       GEOMETRIC,  or  FIRST)  for the mirror. If this attribute is not speci‐
243       fied, the Solaris Volume Manager default value is used.
244
245
246       The <mirror> element takes an optional write attribute  to  define  the
247       mirror  write  options  (PARALLEL, SERIAL, or FIRST) for the mirror. If
248       this attribute is not specified, the  Solaris  Volume  Manager  default
249       value is used.
250
251
252       The <mirror> element takes an optional usehsp attribute to specify if a
253       hot spare pool should be associated with each submirror. This attribute
254       is  specified  as  a  boolean  value,  as  usehsp="TRUE". If the usehsp
255       attribute is specified in the configuration of the <stripe> or <concat>
256       element  used  as  a  submirror,  it  overrides  the  value  of  usehsp
257       attributes for the mirror as a whole.
258
259   Defining Volume by Quality of Service
260       The <volume> element defines volumes (high-level)  by  the  quality  of
261       service  they  should  provide.  (The  <volume> element offers the same
262       functionality that options on the metassist command line can provide.)
263
264
265       The <volume>  element  can  contain  combinations  of  <available>  and
266       <unavailable> elements to determine which components can be included in
267       the configuration.
268
269
270       The <volume> element takes an optional  name  attribute  to  specify  a
271       name.  If the name is not specified, an available name is automatically
272       selected.
273
274
275       The <volume> element takes a required size attribute that specifies the
276       size as value and units (for example, 10TB, 5GB).
277
278
279       The  <volume>  element takes an optional redundancy attribute to define
280       the number of additional copies of data (1-4) to include. In  a  worst-
281       case  scenario,  a  volume can suffer failure of n-1 components without
282       data loss, where redundancy=n. With fault recovery options, the  volume
283       could  withstand  up  to  n+hsps-1 non-concurrent failures without data
284       loss. Specifying redundancy=0 results in a RAID 0 volume being  created
285       (a stripe, specifically).
286
287
288       The  <volume>  element  takes  an  optional  faultrecovery attribute to
289       determine if additional components should be allocated to recover  from
290       component failures in the volume. This is used to determine whether the
291       volume is associated with a hot spare pool. The faultrecovery attribute
292       is a boolean attribute, with a default value of FALSE.
293
294
295       The <volume> element takes an optional datapaths attribute to determine
296       if multiple data paths should be required to  access  the  volume.  The
297       datapaths attribute should be set to a numeric value.
298
299   Defining Default Values Globally
300       Global  defaults can be set in /etc/default/metassist.xml. This volume-
301       defaults file can contain most of the same elements as a volume-request
302       file, but differs structurally from a volume-request file:
303
304           o      The  container  element must be <volume-defaults>, not <vol‐
305                  ume-request>.
306
307           o      The  <volume-defaults>  element  can  contain   <available>,
308                  <unavailable>, <hsp>, <concat>, <stripe>, <mirror>, or <vol‐
309                  ume> elements.
310
311                  Attributes specified by these elements define global default
312                  values,  unless  overridden  by the corresponding attributes
313                  and elements in a volume-request. None of these elements  is
314                  a container element.
315
316           o      The  <volume-defaults>  element  can  contain  one  or  more
317                  <diskset> elements to provide  disk  set-specific  defaults.
318                  The  <diskset>  element  can  contain <available>, <unavail‐
319                  able>, <hsp>, <concat>, <stripe>, <mirror>, or <volume> ele‐
320                  ments.
321
322           o      Settings  specified  outside of a <diskset> element apply to
323                  all disk sets, but can be overridden within  each  <diskset>
324                  element.
325

EXAMPLES

327       Example 1 Creating a Redundant Volume
328
329
330       The  following  example  shows  a  volume request file used to create a
331       redundant and fault tolerant volume of 1TB.
332
333
334         <volume-request>
335           <diskset name="sparestorage"/>
336           <volume size="1TB" redundancy="2" faultrecovery="TRUE">
337             <available name="c2" />
338             <available name="c3" />
339             <unavailable name="c2t2d0" />
340           </volume>
341         </volume-request>
342
343
344       Example 2 Creating a Complex Configuration
345
346
347       The following example shows a sample volume-request file that specifies
348       a  disk  set  name, and specifically itemizes characteristics of compo‐
349       nents to create.
350
351
352         <volume-request>
353
354             <!-- Specify the disk set to use -->
355             <diskset name="mailspool"/>
356
357             <!-- Generally available devices -->
358             <available name="c0"/>
359
360             <!-- Create a 3-way mirror with redundant datapaths and HSPs /
361                   via QoS -->
362             <volume size="10GB" redundancy="3" datapaths="2" /
363                   faultrecovery="TRUE"/>
364
365             <!-- Create a 1-way mirror with a HSP via QoS -->
366             <volume size="10GB" faultrecovery="TRUE"/>
367
368             <!-- Create a stripe via QoS -->
369             <volume size="100GB"/>
370
371         </volume-request>
372
373

BOUNDARY VALUES

375         Attribute       Minimum         Maximum
376         mincomp         1               N/A
377         maxcomp         N/A             32
378         nsubmirrors     1               4
379         passnum         0               9
380         datapaths       1               4
381         redundancy      0               4
382
383
384

FILES

386       /usr/share/lib/xml/dtd/volume-request.dtd
387
388
389
390
391       /usr/share/lib/xml/dtd/volume-defaults.dtd
392
393
394
395
396       /etc/defaults/metassist.xml
397
398
399
400

SEE ALSO

402       metassist(1M), metaclear(1M), metadb(1M),  metadetach(1M),  metahs(1M),
403       metainit(1M),  metaoffline(1M),  metaonline(1M), metaparam(1M), metare‐
404       cover(1M), metareplace(1M),  metaroot(1M),  metaset(1M),  metasync(1M),
405       metattach(1M), mount_ufs(1M), mddb.cf(4)
406
407
408       Solaris Volume Manager Administration Guide
409
410
411
412SunOS 5.11                        27 Apr 2005                volume-request(4)
Impressum