This chapter describes the XVM command line interface (CLI) and the features it provides. The major sections in this chapter are as follows:
To use the XVM CLI, enter the following:
# xvm |
If cluster services have been enabled when you enter this command, you should see the following XVM CLI prompt:
xvm:cluster> |
This prompt indicates that the current domain is cluster, and any objects created in this domain can be administered by any node on the cluster.
You must start cluster services before you can see and access XVM cluster configuration objects. If cluster services have not been enabled when you enter this command on a cluster-configured IRIX system, you should see the following XVM CLI prompt:
# xvm Notice: Cluster services have not been enabled on this cell yet.You will only be able to manipulate local objects until cluster services are started. xvm:local> |
This prompt indicates that the current domain is local, and any objects created in this domain can only be administered by the current node.
You can specify the XVM domain when you bring up the XVM volume manager by using the -domain option of the XVM command:
# xvm -domain domain |
The domain variable can be local or cluster. You may find this option useful for changing the domain of XVM command execution if you are writing a script in which you want to execute a single command in the local domain.
When you are running the XVM Volume Manager in the cluster domain, you can see and modify only the XVM 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, you either change your domain to local with the set domain command, or you use the local: prefix when specifying a physvol name. Similarly, when you are running the XVM Volume Manager in the local domain, you must change your domain to cluster or specify a 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 XVM physical volumes in your local domain, you can use the following format:
xvm:cluster> show local:phys/* |
Similarly, if you are running in the local domain but wish to see the XVM physical volumes in the cluster of which you are a member, you can use the following format:
xvm:local> show cluster:phys/* |
For more information on XVM domains, see “XVM Domains” in Chapter 2.
Once the command prompt displays you can enter XVM CLI commands to configure and manage your XVM logical volumes. These commands are executed interactively, as you supply them.
To configure XVM logical volumes, you need to be logged in as root. However, you can display logical volume configuration information even if you do not have root privileges. 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 enter an individual XVM command directly from the shell by prefacing the command with xvm, as follows:
# xvm [command ...]
|
You can redirect a file of XVM commands into the XVM CLI just as you would redirect input into any standard UNIX tool, as follows:
# 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”.
The XVM CLI includes a help command, which you can use to display the syntax for any of the XVM CLI commands. A question mark (?) can be used as an alias for the help command.
The help command with no arguments produces a list of supported commands. The help command followed by an XVM command displays a synopsis of the XVM command you specify. You can precede the XVM command with the -verbose option to display full help that shows all of the commands options and examples.
The following command displays the synopsis for the slice command:
xvm:cluster> help slice |
The following command displays the full help for the slice command:
xvm:cluster> help -verbose slice |
The keywords you can use for the help command are any of the XVM CLI commands summarized on the xvm(1M) man page. In addition, you can enter the following help commands:
| help names | Displays information on XVM object names | |
| help regexp | Displays information on the regular expressions that you can use when specifying XVM object names |
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 the command. Commands and options are not case sensitive.
For example, you can enter the following command:
xvm:cluster> volume -volname mainvol vol1/data vol2/log vol3/rt |
Alternately, you can enter the following abbreviations:
xvm:cluster> vol -vol mainvol vol1/data vol2/log vol3/rt |
Similarly, you can enter the following full command:
xvm:cluster> show -verbose slice/freds0 |
You can abbreviate the previous command as follows:
xvm:cluster> show -v slice/freds0 |
When you enter XVM commands, the following syntax rules and features apply:
These keywords are reserved by the XVM CLI and may not be used to name objects: vol, stripe, concat, mirror, raid, slice, phys, unlabeled, subvol.
Object names consist of alphanumeric characters and the period ( . ), underscore
( _ ), and hyphen ( - ) characters.Object names cannot begin with a digit.
XVM CLI tokens between <> characters are interpreted as comments.
A backslash ( \ ) at the end of a line acts as a continuation character.
Blank lines and lines beginning with the pound sign ( # ) are ignored.
An exclamation point ( ! ) at the beginning of a command passes the command to the shell.
All XVM objects except slices can have user-defined names supplied to them (if user-defined names are not supplied, default names will be generated). The names of XVM objects are limited to 32 characters in length and cannot begin with a digit.
With the exception of subvolumes, objects are specified using the object name. 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.
The following sections describe various ways XVM objects can be specified. The following topics are covered:
XVM object specification
Piece syntax
XVM object name examples
Regular expressions
XVM objects are specified in a path-like syntax using one of the following forms where objname is the name of the object and vepath is a path leading from one volume element to another.
[domain:][type/]objname [domain:][type/]vepath |
The domain option can be local or cluster. You include the domain option when you are specifying an XVM object that is not in the current domain, as described in “Using the XVM CLI”.
Specifying a path component of “..” for a volume element indicates the parent of the volume element. For example, the following command displays the parent of slice foos0:
show slice/foos0/.. |
Because user-defined names are allowed, it is possible to have ambiguities in the XVM object namespace. When an ambiguous name is supplied to an XVM command and wildcards are not used, the command will generally produce an error message. For information on using wildcards, see “Regular Expressions”.
To remove ambiguity in an object name, an object name may be prefixed with an object type followed by a slash, as in the example concat/concat1. (If there are two objects of different object types named concat1, specifying concat1 alone is not sufficient to identify the object.) Specifying an object type can also make name resolution faster by providing information about the type of object.
Note that unambiguous subvolumes are a 3-tuple: subvol/volname/subvol_name.
The following prefixes are recognized to specify object types. The phys, unlabeled, and foreign object types are described below.
Table 3-1. Prefixes Specifying Object Type
prefix | object type |
|---|---|
vol | Volume volume element |
subvol | Subvolume volume element |
concat | Concat volume element |
stripe | Stripe volume element |
mirror | Mirror volume element |
slice | Slice volume element |
snapshot | Snapshot volume element |
copy-on-write | Copy-on-write volume element |
phys | Physvol |
unlabeled | Unlabeled disk |
foreign | Foreign disk |
The snapshot and copy-on-write volume elements are used with the XVM snapshot feature, described in Chapter 6, “The XVM Snapshot Feature”. XVM on Linux does not support the snapshot feature.
A physvol is a disk that has been labeled by the XVM Volume Manager as an XVM physical volume and has been probed by the system. 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.
An unlabeled disk is a disk that does not have an XVM label or has an XVM label but has not been probed by the XVM subsystem. A disk that was transferred to its current owner by means of the give or steal command is unlabeled until it has been probed, either explicitly with the probe command or during a system reboot.
The path portion of an unlabeled disk is the filesystem path to the volume partition. This can be an explicit path (for example, unlabeled/hw/rdisk/dks0d4vol) or a relative path (for example, unlabeled/dks0d4vol). SAN disk paths have multiple components (for example, unlabeled/2000006016fe057a/lun4vol/c11p0).
A foreign disk is an XVM disk that cannot be administered by the current owner, either because the disk is owned by another node or another cluster. The format of the path portion of a foreign disk is the same as the path portion of an unlabeled disk.
XVM volume elements can also be specified using a path-like syntax where the components of the path are volume element names or piece numbers under the parent. For example: vol/fred/data/concat0/phys0 refers to the ve phys0, whose parent is concat0, which is the data subvolume of volume fred. Additionally, concat0/0 refers to the zero child (piece) of the ve concat0. The piece syntax is helpful when you want to target a volume element without knowing its name.
Figure 3-1 shows the layout of an XVM logical volume with system-generated names.
Table 3-2 shows examples of how you can use piece syntax to specify individual volume elements in the XVM logical volume illustrated in Figure 3-1.
Table 3-2. Specifying Logical Volume Elements Using Piece Syntax
XVM object | Alternate Object Specification |
|---|---|
concat/concat0 | vol0/data/0 |
stripe/stripe0 | vol0/data/0/0 |
stripe/stripe1 | vol0/data/0/1 |
mirror/mirror0 | vol0/data/concat0/stripe0/0 |
mirror/mirror2 | vol0/data/concat0/stripe1/0 |
slice/dsk6s0 | vol0/data/0/1/1/0 |
The following examples show how a variety of XVM objects can be specified.
| vol0 | The object named vol0 | |
| unlabeled/dks0d4 | The unlabeled disk on controller 0, drive 4 | |
| mirror/mirror6 | The mirror volume element named mirror6 | |
| concat0/0 | The leftmost piece of concat0 | |
| vol0/data/0 | The child of the data subvolume of volume vol0 | |
| stripe0/freds0 | The volume element named freds0 under the stripe stripe0 | |
| unlabeled/2000006016fe0ed0/lun3vol/clip0 | The SAN disk whose volume partition path is /dev/rdsk/2000006016fe0ed0/lun3vol/clip0 | |
| foreign/dks5d43vol | The disk dks5d43vol, which cannot be administered by the machine displaying this object name |
Regular expressions can be used in specifying object names in XVM CLI commands. The wildcard (*), ?, and [ ] characters are recognized and have their standard regular expression meanings as supported through the fnmatch(3G) function. Regular expressions in an XVM CLI command are limited to the rightmost component of an XVM object path.
The following examples show how regular expressions can be used in XVM CLI command:.
| * | Matches all objects | |
| 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/dks[34]d* | Matches all unlabeled disks on controllers 3 and 4 |
Specifying a volume element path ending in / is equivalent to specifying a volume element path ending in /*.
A volume element path which consists of an object type keyword is equivalent to specifying the keyword followed by /*. For example, a show slice command is equivalent to a show slice/* command.
Under IRIX, XVM logical volumes are contained in the following directories:
If you are not running in a cluster environment, then all the logical volumes are considered to be local volumes.
The device names for XVM logical volume in these directories are of the form volname, subvolname where volname is the name of the XVM logical volume and subvolname is the name of the subvolume to be accessed under that volume. The shorter name volname can optionally be used instead of volname,subvolname when referring to the data subvolume. For example, /dev/cxvm/fred,data and /dev/cxvm/fred both refer to the block special file of the data subvolume under volume fred.
Under Linux, block devices for XVM logical volumes used for a host's local volume are contained in the /dev/lxvm directory. For compatibility with earlier releases, support is also provided for the /dev/xvm/local/vol/volname/data/block directory.
For information on names of objects within XVM logical volumes, see “Object Names in XVM”.
In general, commands that create or manipulate objects will print out the name of the created or target object upon successful completion, as in the following example:
xvm:cluster> concat -tempname slice/wilmas0 slice/barneys0 </dev/cxvm/vol0> concat/concat0 |
You can use shell substitution to feed the output of one command into another. For example, under the Korn shell the following command would create a concatenated volume element with a volume name of fred and the physvols phys1 and phys2 as the components.
$ xvm concat -volname fred $(xvm slice -all phys1) $(xvm slice -all \ phys2) |
Under csh or sh, the syntax for the command is as follows:
$ xvm concat -volname fred `xvm slice -all phys1` `xvm slice -all \ phys2` |
Commands that fail, or for which the manipulated object does not make sense (such as delete, for example), do not print out the target object name.
As shown, commands that create or modify volume elements also display the subvolume block-special name that the target ve belongs to inside of <> symbols. For example, the command slice -all phys1 produces the following output (if successful), where slice/phys1s0 is the name of the slice created, and /dev/cxvm/phys1s0 is a path to the subvolume block-special that can be opened to gain access to the slice:
</dev/cxvm/phys1s0> slice/phys1s0 |
Tokens that appear inside of <> symbols are treated as comments by the CLI. This ensures that even though a command that creates a volume element displays the block-special name, that output is inside of <> symbols and is ignored by the CLI when you feed the output of one command into another.
The XVM commands can be categorized as safe or unsafe. An unsafe command is one that will in some way affect the address space of the subvolume that the ve is under, such as detaching or deleting a child of a concat ve. Safe commands do not affect the address space of the subvolume, such as detaching or deleting all but the last child of a mirror ve (detaching or deleting the last child is unsafe).
Safe commands can always be issued regardless of the open state of the effected subvolume, whereas unsafe commands can be issued only if the subvolume is not open. Mounted subvolumes are always open, however a subvolume may also be open without being mounted, for example if an application is accessing the raw subvolume.
Unsafe commands to open subvolumes will result in an error by default, but certain commands have a -force option to override that behavior. Conversely, certain commands have a -safe option, which will enforce the safe checks even if the subvolume is not open.