To configure XVM volumes, you must be logged in as root.

However, you can display configuration information even if you do not have root privileges.

To use the xvm CLI interactively, enter the following:

# /sbin/xvm

If the required CXFS services (see “CXFS Service Requirements for Cluster Domain” in Chapter 2) have been started when you enter this command, you should see the following prompt:

xvm:cluster>

This prompt indicates that the current domain is the cluster domain, and any objects created in this domain can be administered by any node in the CXFS cluster.

---

Note: You must start the required services before you can see and access XVM cluster configuration objects.

---

However, if the services have not been enabled when you enter the xvm command, the prompt will appear as follows:

xvm:local>

To explicitly specify the XVM domain, use the -domain option:

# /sbin/xvm [-domain] domaintype

The domaintype variable can be local or cluster. You may find this option useful for changing the domain if you are writing a script in which you want to execute a single command in the local domain.

---

Note: When you are running XVM in the cluster domain, you can see and modify only the XVM physical volumes (physvols) that are also in the cluster domain, even if you are running from the node that is the owner of a local physvol.

---

To see and modify local disks, either change to the local domain with the set domain command or use the local: prefix when specifying a physvol name. Similarly, when you are running XVM in the local domain, you must change to the cluster domain or include the cluster: prefix when specifying a physvol that is owned by the cluster.

For example, if you are running in the cluster domain but wish to see the physvols in the local domain, enter the following:

xvm:cluster> show local:phys/*

Similarly, if you are running in the local domain but wish to see the XVM physvols in the cluster of which you are a member, enter the following:

xvm:local> show cluster:phys/*

For more information on XVM domains, see “Local Domain and Cluster Domain” in Chapter 2.

After the command prompt displays, you can enter commands to configure and manage volumes. These commands are executed interactively, as you supply them.

When you have finished executing xvm CLI commands, you return to your shell by entering the exit command. (You can also use bye or quit as an alias for the exit command.)

You can also enter an individual xvm CLI command directly from the shell by prefacing the command with xvm, as follows:

# /sbin/xvm [-domain local|cluster][xvmcommand ...]

For example, to display the brief syntax for the concat command:

# xvm help concat
concat -tempname [-pieces N] [-vename concatname] [ve ...]
concat -volname name [-pieces N] [-vename concatname] [ve ...]

For more information, see the xvm(8) man page.

You can redirect a file of xvm CLI commands into the xvm CLI just as you would redirect input into any standard Linux tool. For example, to redirect the contents of the file myscript:

# xvm < myscript

Alternately, you can enter the following:

# cat myscript | xvm

For information on using shell substitution to feed the output of one command into another, see “Command Output and Redirection”.

To see a list of supported commands, enter the following:

xvm:cluster> help

To see a brief synopsis of a command, enter the following:

xvm:cluster> help keyword

The keyword is any of the commands listed in Table 4-1 plus the general help topics described in Table 4-2.

For example, the following command displays the synopsis for the slice command:

xvm:cluster> help slice

To see the full help text for a command, include the -verbose option (which you can abbreviate to -v):

xvm:cluster> help -verbose keyword

For example, the following command displays the full help for the slice command:

xvm:cluster> help -v slice

The xvm CLI commands may be abbreviated to any unique substring. Command options may be abbreviated to any substring that is unique among the options supported by that command. Commands and options are not case sensitive, but object names are case sensitive.

For example, are examples of full commands and their abbreviations:

xvm:local> volume -volname mainvol vol1/data vol2/log vol3/rt
xvm:local> vol -vol mainvol vol1/data vol2/log vol3/rt

xvm:local> show -verbose slice/freds0
xvm:local> sh -v slice/freds0

When you enter xvm CLI commands, the following syntax rules and features apply:

You can explicitly name the following XVM objects:

---

Note: Slice names are always generated by XVM.

---

If you do not supply a name when you create the object, XVM will generate a temporary name that refers to the object type and generation counter (starting from 0) within the XVM topology tree, such as the following:

The generated name may not persist across reboots. To have a permanent name, you must either specify the name at creation time or use the change command. See “Modifying Volume Elements with the change Command ” in Chapter 5.

The following naming rules apply:

With the exception of subvolumes, objects are specified using the object name, using one of the following forms:

[domain:][prefix/]name
[domain:][prefix/]path

where:

---

Note: Subvolume objects must be specified by prefixing the subvolume name with its volume name followed by a slash (/). For example: fred/data. In this example, fred is the name of the volume and data is the name of the subvolume.

---

Because user-defined names are allowed, it is possible to have ambiguities in the XVM object namespace. For example, if there are two objects of different object types named fred, specifying fred alone is not sufficient to identify the object.

You can also use wildcards; see “Regular Expressions”.

To remove ambiguity in an object name, include the type prefix followed by a slash, such as concat/concat1. Specifying an object type can also make name resolution faster by providing information about the type of object.

---

Note: The following 3-tuple construction is always unambiguous: subvol/volname/subvol_name

---

If you specify an ambiguous name to an xvm CLI command without a wildcard, the command will generally produce an error message.

Table 4-3 lists the object prefixes.

For example, phys/fred refers to the XVM physvol named fred. The path portion of the name is the name that was given to the physvol at the time it was labeled.

The path portion of an unlabeled disk is the filesystem path to the volume partition. For example:

The format of the path portion of a foreign disk is the same as the path portion of an unlabeled disk.

For more information, see “XVM Objects” in Chapter 2.

XVM volume elements can also be specified using a combination of component names and piece numbers, which reflect position of a component in the XVM topology tree. For example, concat0/0 refers to the zero piece (child) of the volume element concat0. The piece number syntax is helpful when you want to target a volume element without knowing its name.

Figure 4-1 shows an XVM topology tree that uses system-generated names for the volume and all of its children, and their corresponding piece numbers.

Figure 4-1. XVM Volume with System-Generated Names and Piece Numbers

The first child of a given volume element is considered the leftmost child (piece 0), and the last child is considered the rightmost child.

Table 4-4 shows examples of how you can use piece syntax to specify individual volume elements illustrated in Figure 4-1.

The following examples show how a variety of XVM objects can be specified:

You can use regular expressions when specifying object names. The following characters are recognized and have their standard regular expression meanings as supported through the fnmatch(3) function:

Regular expressions are limited to the rightmost component of an XVM object path. For example:

Example		Description
*		Matches all objects Note: At the shell command line, you must protect the * character by enclosing it within quotation marks so that it is interpreted correctly by the shell. For example: # xvm show '*' The protection is not required when you are using the xvm CLI interactively.
vol/*		Matches all volumes
slice/*s0		Matches all slices ending in s0
concat0/*		Matches all children of concat0
subvol/log*		Matches all log subvolumes
fred*		Matches all objects beginning with fred
unlabeled/*		Matches all unlabeled disks

For example, to show all objects starting with I:

xvm:cluster> show I*
vol/I_Love_Lucy 0 online

Specifying a volume element path ending in / is equivalent to specifying a volume element path ending in the /* character sequence.

A volume element path that consists of an object type keyword is equivalent to specifying the keyword followed by the /* character sequence. For example, the following commands are equivalent:

xvm:cluster> show slice
xvm:cluster> show slice/*