vxmake - create Veritas Volume Manager configuration records

vxmake [-pV ] [-g diskgroup] [-o useopt] [-U usetype] [-T a|o] [-d descfile]

vxmake [-pV ] [-g diskgroup] [-o useopt] cache name
    cachevolname=cachevol [attribute=value] ...

vxmake [-pV ] [-g diskgroup] [-o useopt] dco name [attribute=value] ...

vxmake [-pV ] [-g diskgroup] [-o useopt] plex name [attribute=value] ...

vxmake [-pV ] [-g diskgroup] rlink name [attribute=value] ...

vxmake [-pV ] [-g diskgroup] rvg name [attribute=value] ...

vxmake [-pV ] [-g diskgroup] [-o useopt] sd name [attribute=value] ...

vxmake [-pV ] [-g diskgroup] [-o useopt] [-U usetype] vol name [attribute=value] ...

vxmake [-g diskgroup] [-m "ch_initopt"] [-c "ch_addopt"]
    [-o makedev={on|off}] [-o compvol_access={read-only|read-write}]
    vset name appvols=vol[,vol]... [attribute=value] ...

The vxmake utility creates object records (for example, for subdisks, plexes, and volumes) for Veritas Volume Manager (VxVM). Records can be created entirely from parameters specified on the command line, or they can be created using a description file.

vxmake can also create a data change object (DCO) that is used to implement Persistent FastResync on a volume, a cache object that is used with space-optimized snapshots, a volume set that is used to implement multi-volume support.

When the Volume Replicator (VVR) option is available, vxmake can also create RVG and RLINK records. RVG and RLINK records only support gen usage.

Note: Although it is possible to use vxmake to create new volumes from an appropriate description file, it is recommended that you use vxassist or the graphical user interface instead.

Note: The Configuration Backup and Restore utilities, vxconfigbackup and vxconfigrestore, are the recommended method for backing up and restoring volume hierarchies.

If no operands are specified, then a description file is used to specify what records to create. By default, this description file is read from the standard input. If operands are specified, then the first operand is a keyword that determines the object to build, the second operand is the name of the object to be created, and additional operands specify attributes for the object to be built. An attribute given on the command line is specified in the same manner used with the description file (with multiple attributes given, one attribute per operand), except that the double-quote convention is not needed. See the EXAMPLES section for sample uses.

For convenience, a special attribute form can be used for subdisks specified directly from the command line. This special attribute form is:

devicepath,offset[,len]

or

medianame,offset[,len]

The first form specifies a subdisk location by device path, offset within that device, and length. The second form specifies the subdisk location by a disk media record name, offset within the disk’s public region, and length. Optionally, the length can be specified with a len=length attribute instead. If a device path is specified, then it must match the device path for the public region of a known disk in the indicated disk group.

More than one record, including more than one volume or plex hierarchy, can be specified in a single description file. vxmake attempts to create all records within a single transaction, so that either all records are created or no records are created. This is the default behavior.

The -T option allows users to select transaction control that differs from the default behavior when restoring records within a volume hierarchy from a description file. This is particularly helpful with layered volume hierarchies that include subvolumes.

See vxmake(4) for a specification of vxmake descriptions.

Descriptions of records within a volume hierarchy are filtered through a usage-type-specific utility, as appropriate for the usage type, before the records are actually created. Subdisks and plexes that are not specified within a volume hierarchy are filtered by the gen usage type. The usage-type utilities may change the descriptions so that certain fields are ignored or set up with initial values. Plex or subdisk records to be associated with a volume or plex may also be changed if the association is indicated in the description, even if the plex or subdisk record is not explicitly specified.

A usage type must be specified for every volume record, either through setting the usetype field in the volume record description, or through the -U option to vxmake.

-c "ch_addopt"
	Specifies a string that is passed to the vset_addvol content handler operation (if any) when volumes are added to a volume set (vset) that is being created.
-d descfile	Specify the name of a description file to use for building subdisks, plexes, volumes, RVGs and RLINKs. If the descfile option argument is -d, then the description file is read from the standard input. If no operands are specified, and no descfile is specified, then a description file is read from the standard input. This option is ignored for records that are specified directly on the command line.
-g diskgroup	Specify the disk group for the operation. The disk group can be specified either by name or by disk group ID. If this option is not specified, the default disk group is determined using the rules given in the vxdg(1M) manual page.
-m "ch_initopt"
	Specifies a string that is passed to the vset_initset content handler operation (if any) when a volume set (vset) is initialized.
-o compvol_access={read-only|read-write}
	If set to read-only, only reads are allowed on the raw device of each component volume of a volume set that is being created. If set to read-write, both reads and writes are allowed. This option only has any effect if the -o makedev=on option is also enabled for the volume set. If not specified, the default setting is read-only if -o makedev=on is specified.
-o makedev={on|off}
	If set to on, sets up the raw device nodes for each of the component volumes in the volume set that is being created. If set to off (default), no raw device nodes are created.
-o useopt	Give usage-type-specific options to the usage type utility.
-p	Print a list of all changes that would be made to the standard output, but do not make those changes. The output is in the vxmake description file format. All computable and potentially useful attributes are printed for new records. For records that would be modified, only those attributes that would change are printed, along with an extra attribute declaration, CHANGED=yes. In this way the -p option performs a preview run of the utilities.
	This option is intended for use with higher-level tools that preview record creations, particularly with respect to usage-type-dependent attribute modifications.
-T	This option controls the unit of work that vxmake uses to make records within a single transaction when restoring records from a description file. If the option argument is a or the -T option is absent altogether, then vxmake attempts to create all records within a single transaction, so that either all records are created or no records are created. This behavior is considered the default behavior and it is backward- compatible with previous releases of VxVM.
	If the option argument is o, then one complete top-level object (Volume hierarchy, dissociated plex hierarchy, or dissociated subdisk hierarchy) is created at a time, and if multiple top-level objects are to be created from the same description file, then vxmake attempts to create each one a top-level object at a time in its own transaction. Note that should some objects be creatable and some not, the configuration results in those objects that vxmake was actually able to create. This option can be used for any record hierarchy. Because record hierarchies with layered volumes may contain many subordinate records (such as subvolumes), the -T o option is particularly useful for safely creating these kinds of objects.
-U usetype	Use usetype as the default usage type for volumes. This option has no effect if only subdisks and plexes are created, or if the usage type for a volume is specified directly with the description file variable usetype.
-V	Display a list of utilities that would be called from vxmake, along with the arguments that would be passed. The -V option performs a preview run of the utilities; the utilities are not actually called, and no changes are made to the volume configuration database.

The only attributes that must be specified are the path and len attributes for subdisk records, and a usage type for volume records. In addition, if the layout attribute for a plex record is set to STRIPE, then a positive value must be specified for the stwidth attribute. Also, if no subdisks are specified for a plex of the STRIPE layout, the ncolumn attribute must be specified.

Attempts to specify certain attributes are ignored by vxmake. Some attributes are ignored by the switchout (usage-type independent) vxmake itself. The usage-type dependent vxmake may cause additional attributes to be ignored.

The sections that follow provide information on the attributes that can be specified for subdisk, plex, and volume creation.

Fields that can be specified for subdisks are: tutil0, tutil1, tutil2, putil0, putil1, putil2, daname, dmname (or disk), path, comment, devoffset, dmoffset, len and dmrid.

The disk specification for subdisks uses one of following fields, in order of precedence: dmrid, dmname, daname, or path. The dmrid field is used, if non-zero. One of the other fields is used if defined to a non-empty string. If the path field is the only field used, it must define the block device path for a partition containing the public region of a disk in the requested disk group.

With path, the devoffset field is used as an offset into the partition; otherwise dmoffset is used as an offset into the private region. This distinction is important if the public region does not begin at the beginning of its partition.

Specification of a disk in some form (including possibly the special forms devicepath,offset,length or medianame,offset,length) is required. Specification of the len field is also required. All other fields default to zero (for numbers) or empty strings (for strings).

Fields that can be specified for plexes are: tutil0, tutil1, tutil2, putil0, putil1, putil2, comment, layout, ncolumn, stwidth, sd, and logsd.

There are no required fields for plex records. All fields default to zero (for numbers) or empty strings (for strings). The layout field defaults to concat.

If the layout field is set to stripe or raid5, then the stwidth attribute must be specified. If the layout field is set to concat, the ncolumn field cannot be specified.

An sd specification names the subdisks to associate with the plex. The specification optionally names the offsets of the subdisks within the plex. If no offsets are specified, then the subdisks are directly concatenated in the order indicated. If the sd attribute is specified for a striped plex and ncolumn is not specified, ncolumn will default to the column of the subdisk with the highest column specification. As a special case, if ncolumn is not specified and the sd does not specify columns or offsets for the subdisks, then each subdisk will be placed in its own column at an offset of zero in the order they are specified and the plex’s ncolumn attribute is set to the number of subdisks specified.

A logsd specification names a subdisk to associate as a special log subdisk for recording volume activity as part of the DRL or DCM logging features.

Fields that can be specified for volumes are: comment, usetype, startopts, readpol, prefname, minor, user, group, mode, len, writeback, writecopy, exclusive, primary_datavol, logtype, plex, and dco_name.

Specification of a usage type is required, either using the -U option on the command line, or using the usetype attribute. Specification of a usetype attribute overrides a value specified with -U. All other fields have default values: readpol defaults to round; user and group both default to 0 (root); mode defaults to u=rw (mode 600); writeback and writecopy default to on; exclusive defaults to off; len defaults to the length of the shortest associated plex (or zero, if no plex associations are requested); all other numeric fields default to zero, and all other string fields default to empty strings.

A plex specification names the plexes to associate with the volume. The order of plexes in this list is not important.

The value of the prefname field is relevant only if the readpol attribute is set to prefer.

A dco_name specification names the data change object (DCO) to associate with the volume.

The vxmake vset command creates a volume set that contains the volumes listed as comma-separated arguments to the appvols attribute. The -c and -m options can be used to define content handler strings that are used by the handler utilities for the volume set.

If the -o makedev=on option is specified, raw device nodes are set up for each of the component volumes in the volume set that is being created. If set to off (default), no raw device nodes are created.

If the -o compvol_access option is specified in conjunction with the -o makedev=on option, this specifies the degree of access that is allowed to the raw device nodes. If set to read-only (default), only reads are allowed on the raw device of each component volume of a volume set that is being created. If set to read-write, both reads and writes are allowed.

Note: If the output from the vxprint -m command is fed to the vxmake command to recreate a volume set, the vset_devinfo attribute must set to off. Use the vxvset set command to re-enable raw device access with the desired access mode as described in the vxvset(1M) manual page.

The editable fields are appvols, ch, comment, and context.

See vxvset(1M) for more information about volume sets.

The vxmake cache command creates a cache object. cachename, for a pre-existing volume, cachevol. This allows the volume to be used as the cache for one or more space-optimized snapshots (see vxsnap(1M) for details).

The editable fields are autogrow, autogrowby, highwatermark, maxautogrow and regionsize. See vxcached(1M) and vxmake(4) for a description of these attributes.

Note: The region size that is specified for a volume using the vxsnap prepare command must be greater than or equal to the region size that is specified for the cache object.

The following example commands illustrate how to create and enable a 1GB mirrored cache with a region size of 32KB:

vxassist -g mydg make cachevol 1g layout=mirror init=active \0   mydg16 mydg17
vxmake -g mydg cache cobjmydg cachevolname=cachevol \0   regionsize=32k
vxcache -g mydg start cobjmydg

Note: Once set on a cache, the region size cannot be changed.

Fields that can be specified for data change objects (DCOs) are: tutil0, tutil1, tutil2, putil0, putil1, putil2, comment, log, and dco_sp_num,

A log specification defines the volume that is to be associated as a DCO volume. A DCO volume tracks changes for the DCO. The following example uses this field to associate myvol_dcl with the DCO myvol_dco_obj:

vxmake -g mydg dco myvol_dco_obj log=myvol_dcl

dco_sp_num stores the number of snap records that are associated with the DCO.

The attributes dms and spares may optionally be set for storage pools. The dms attribute specifies a comma-separated list of disk-media record names that belong to the storage pool. The spares attribute specifies a comma-separated list of disk-media record names that are spares for the storage pool. None of the named disks may already be associated with any higher-level record (such as a subdisk) or other storage pool.

For the -d option, the usual record attributes such as comment, tutil and putil may be set using the output from the vxprint -m. In this output, the attributes auto and type are specific to storage pools, and refer to members of the storage pool record. The appvol_num, app_vols, dm_num and spare_num attributes cannot be changed or set as they are updated automatically.

If the output from vxprint -m contains intent information, the created storage pools are accessible as normal objects, but they do not have any associated intent information.

Fields that can be specified for RVGs are: tutil0, tutil1, tutil2, putil0, putil1, putil2, comment, datavol, vset, srl, rlink, primary, bunker, user, group, mode.

There are no required fields for rvg records. All fields default to zero (for numbers) or empty strings (for strings). The datavol attribute is a list of the name or names (separated by a comma) of the data volumes to be associated with the rvg. The vset attribute is the name or a comma-separated list of names of the volume sets to be associated with the rvg. The srl attribute is the name of the Volume Replicator log volume to be associated with the rvg. The rlink attribute is a list of name or names (separated by a comma) of the RLINK to be associated with the rvg. The order of RLINKs in the list is not important. Secondary RVGs can have at most one RLINK. The primary attribute should be set to true for the primary rvg and false for all secondary RVGs. The bunker is a boolean attribute and should be set to true for the bunker rvg. It is set to false by default.

Fields that can be specified for RLINKs are: tutil0, tutil1, tutil2, putil0, putil1, putil2, comment, synchronous, local_host, remote_host, remote_dg, remote_rlink, bunker, timeout, packet_size, protocol, latency_high_mark, latency_low_mark, latencyprot, srlprot, compression, and bandwidth_limit.

There are no required fields for RLINK records. All fields default to zero (for numbers), empty strings (for strings), off (for compression, synchronous, latencyprot and srlprot), or none (for bandwidth_limit), with the exception of timeout, packet_size, latency_high_mark, and latency_low_mark, which default to some reasonable non-zero values. The timeout (milliseconds to wait for connection timeouts) and packet_size (bytes per packet) attributes should be tailored to the system on which VVR is running. The remote_host attribute is the name of the remote primary or secondary node. The remote_dg attribute is the name of the remote diskgroup. The remote_rlink attribute is the name of the remote RLINK. The bunker is a boolean attribute. If set to true, the RLINK is considered to be a bunker RLINK. It is set to false by default. All RLINKs associated with a bunker RVG are bunker RLINKs. On the Primary RVG, this field is set on the RLINK to the bunker Secondary. srlprot attribute for bunker RLINK should be set to off or override, default is off for bunker RLINK. The protocol argument specifies the network transport protocol that is used with the RLINK: UDP for UDP/IP or TCP for TCP/IP. For bunker RLINK, protocol can also be set to STORAGE, this can be used when secondary Diskgroup is imported on primary host itself. The compression attribute specifies whether compression is on or off. The bandwidth_limit argument specifies the maximum network bandwidth to be used by the RLINK.

The fsgen and gen usage-type-specific utilities that support vxmake are used by the switchout vxmake utility as filters that set defaults for plex and volume states.

Subdisk fields are set, checked, or modified as follows:

len	Subdisk lengths are required to be set to a non-zero value.
tutil0	This field is cleared.
Plex fields are set, checked, or modified as follows:
tutil0	This field is cleared.
state	If the plex is to be associated with a volume, the state field is set to EMPTY; otherwise it is cleared.
Volume fields are set, checked, or modified as follows:
tutil0	This field is cleared.
state	This field is set to EMPTY.

Attempts to associate an existing subdisk or plex with a new plex or volume will be refused, unless the putil0 field for the existing record is empty.

The putil0 fields are not set, and their contents are preserved.

The raid5 usage-type-specific utilities that support vxmake are used by the switchout vxmake utility as filters that set defaults for plex and volume states.

Subdisk fields are set, checked or modified as follows:

len	Subdisk lengths are required to be set to a non-zero value.
tutil0	This field is cleared.
Plex fields are set, checked, or modified as follows:
tutil0	This field is cleared.
state	If the plex is to be associated with a volume, the state field is set to EMPTY; otherwise it is cleared.
Volume fields are set, checked, or modified as follows:
tutil0	This field is cleared.
state	This field is set to EMPTY.

Attempts to associate an existing subdisk or plex with a new plex or volume will be refused, unless the putil0 field for the existing record is empty.

The putil0 fields are not set, and their contents are preserved.

The raid5 specific vxmake utility will only allow one plex with a layout of raid5 to be associated with a volume. Plexes not of the raid5 layout are associated as RAID-5 log plexes.

The following is an example of a vxmake description file:

#rectyp #name #options
sd disk3-01 disk=disk3 offset=0 len=10000
sd disk3-02 disk=disk3 offset=25000 len=10480
sd disk4-01 disk=disk4 offset=0 len=8000
sd disk4-02 disk=disk4 offset=15000 len=8000
sd disk4-03 disk=disk4 offset=30000 len=4480
plex db-01 layout=STRIPE ncolumn=2 stwidth=16k
 sd=disk3-01:0/0,disk3-02:0/10000,disk4-01:1/0,disk4-02:1/8000,disk4-03:1/16000
sd ramd1-01 disk=ramd1 len=640
   comment="Hot spot for dbvol"
plex db-02 sd=ramd1-01:40320


vol db usetype=gen plex=db-01,db-02
   readpol=prefer prefname=db-02
   comment="Uses mem1 for hot spot in last 5m"

This description specifies a gen type volume that contains two plexes: a volatile memory disk plex (db-02), which is preferred, and a physical disk plex (db-01). The memory disk plex is sparse and covers only the last 640 sectors of the 40960-sector length of the volume. The physical disk plex is striped across two 20480-sector columns. Column zero contains two subdisks and column one contains three subdisks. The plex offset specified for each subdisk concatenates the subdisks contiguously in their respective columns.

Note: More than one attribute may be declared on a single line if separated by one or more tabs or spaces. An attribute and its specified values must be defined on the same line. Attributes that are specified on lines subsequent to the first line for an object definition must be preceded by one or more tabs or spaces.

For striped or RAID-5 plex subdisk associations, if one number is specified for the column and column offset field, the number is interpreted as a column number and the subdisk is associated at the end of the column in the order it appears in the subdisk list. The same subdisk association list for plex db-01 could be re-written as follows:

sd=disk3-01:0,disk3-02:0,disk4-01:1,disk4-02:1,disk4-03:1

The following is an example of a vxmake description file which specifies an RVG that contains two RLINKs with different transport protocols, two data volumes, one vset and an srl volume:

#rectyp #name #options
rlink rl01 protocol=UDP remote_host=egbert
   remote_dg=rmtdg remote_rlink=rl0A
rlink rl02 protocol=TCP remote_host=robert
   remote_dg=rmtdg remote_rlink=rl0B
rvg rvg01 rlink=rl01,rl02 primary=true
   datavol=vol02,vol03 vset=vset01 srl=srl01

The following is a simple sequence of commands to create a hierarchy with one subdisk, one plex, and one volume:

vxmake -g mydg sd mydg07-01 mydg=mydg07 len=10000  comment="mydg07 subdisk 1"
vxmake -g mydg plex demo-1 sd=mydg07-01  comment="Demo volume, plex 1"
vxmake -g mydg -U gen vol demo plex=demo-1  comment="Demo gen volume"

The next example shows how to use vxmake to create a volume with an associated DCO object and DCO volume:

# First make the DCO volume
vxmake -g mydg sd mydg08-01 disk=mydg08 len=264  comment="dco vol subdisk"
vxmake -g mydg plex dco_plex-1 sd=mydg07-01  comment="dco vol plex 1"
vxmake -g mydg -U gen vol dcovol plex=dco_plex-1  comment="dco vol"


# Next make the DCO itself
vxmake -g mydg dco Demo_dco log=dcovol  comment="dco for Demo vol"


# Finally make the volume and associate the DCO with it
vxmake -g mydg sd mydg07-01 disk=mydg07 len=10000  comment="mydg07 subdisk 1"
vxmake plex demo-1 sd=mydg07-01  comment="Demo volume, plex 1"
vxmake -U gen vol demo plex=demo-1 dco_name=Demo_dco  comment="Demo gen volume"

The vxmake utility exits with a non-zero status if the attempted operation fails. A non-zero exit code is not a complete indicator of the problems encountered, but rather denotes the first condition that prevented further execution of the utility.

See vxintro(1M) for a list of standard exit codes.

/usr/lib/vxvm/type/usetype/vxmake
	Usage-type-specific utility for filtering volume hierarchy descriptions.

The vxmake command supports specifying an IPv6 hostname or an address for the local_host and remote_host fields of RLINKs, in addition to an IPv4 address.

vxassist(1M), vxcache(1M), vxcached(1M), vxconfigbackup(1M), vxconfigrestore(1M), vxdisk(1M), vxdg(1M), vxintro(1M), vxmake(4), vxsnap(1M), vxvset(1M)