Provided by:
evms-cli_2.5.5-26ubuntu2_i386 
NAME
evms - The evms command starts the Enterprise Volume Management System
(EVMS) Command Line Interpreter (CLI). These command line options
control where the EVMS CLI gets commands from and how it interprets
those commands. This document begins by explaining the parameter
option descriptions and then goes on to explain the commands that can
be entered at the CLI’s prompt.
SYNOPSIS
evms [-b] [-c] [-d debug-level] [-f filename] [-h] [-m engine-mode] [-n
node] [-r parameter] [-s] [-p] [-v[[0-2]]] [-rl parameter ...]]
DESCRIPTION
The CLI does not accept EVMS commands as part of the command line used
to invoke it. The parameter options on the command line determine
where the CLI gets the commands from and how it interprets those
commands. By default, the CLI prompts the user for EVMS commands. To
exit the EVMS CLI, type quit or exit.
PARAMETER OPTIONS
The following parameters are available for use during the initial call
to invoke the EVMS CLI.
-b Tells the EVMS CLI to run in batch mode. Any time there is a
prompt for input from the user, the default value should be
accepted automatically. This is the default behavior with the
-f option.
-c Indicates that changes are not committed to disk until the user
exits the CLI. Normally, changes are committed to disk after
each individual command is completed, even if there are multiple
commands specified on the same command line.
-d debug-level sets the debug level that controls how much
information is logged in /var/log/evms-engine.log. debug-level
is specified as one of the following: critical, serious, error,
warning, default, details, extra, entry_exit, debug, or
everything.
-f filename tells the CLI to accept input from the file specified
by filename. When all of the commands in filename have been
processed, the CLI will exit.
-h Provides help on invoking the EVMS CLI. To get help on commands
accepted by the CLI, invoke the Interpreter, enter the word help
at the prompt, and press Enter.
-m engine-mode tells the CLI the mode in which it should open the
EVMS Engine. engine-mode is either ReadOnly, ReadWrite, or
Daemon. Daemon mode should only be specified when using the CLI
to start the EVMS Engine daemon on nodes in a cluster.
-n node tells the CLI that all commands are intended for the given
node name in a cluster.
-p Tells the CLI to parse commands only. Errors found during
parsing will be reported, but the commands will not be executed.
-r Tells the CLI that the next command line argument is a
replacement parameter. See examples below.
-s Tells the CLI to prompt for a single command line and then exit.
Normally, the CLI will prompt for command lines until it
receives the quit or exit command.
-v Enables verbose mode 2.
-v0 Disables verbose mode. Verbose mode 0 allows EVMS Engine status
messages to be discarded whenever changes are committed to disk.
-v1 Enables verbose mode 1. Verbose mode 1 allows EVMS Engine
status messages to be displayed whenever you commit changes to
disk. The messages are displayed one per line on the screen.
-v2 Enables verbose mode 2. Verbose mode 2 allows EVMS Engine
status messages to be displayed whenever you commit changes to
disk. The messages are displayed using a single line on the
screen. This means that the current message is erased, and the
next message is displayed in its place.
-rl tells the EVMS CLI that all of the remaining command line
arguments are replacement parameters. Replacement parameters
are accessed in EVMS commands using the $(x) notation, where x
is a number identifying which replacement parameter to use.
Replacement parameters are assigned numbers (starting with 1) as
they are encountered on the command line.
Example:
evms -c -f testcase -r sda -r sdb
sda is replacement parameter 1
sdb is replacement parameter 2
Example:
evms -r sda -c -f testcase -rl sdb sdc
sda is replacement parameter 1
sdb is replacement parameter 2
sdc is replacement parameter 3
Example:
evms -c -f testcase -rl sda 100
sda is replacement parameter 1
100 is replacement parameter 2
if testcase contains the command:
allocate:$(1)_freespace, size=$(2)MB
then this command becomes:
allocate: sda_freespace, size=100MB
COMMANDS FOR THE EVMS PROMPT
The following commands can be typed at the EVMS CLI prompt "EVMS: ".
This prompt appears when the EVMS CLI is ready to accept a command.
All EVMS CLI commands and key words are case insensitive.
The names and values that you supply are case sensitive.
Any amount of whitespace can appear between commands, delimiters, and
values.
ACTIVATE
The Activate command is used to activate volumes or storage objects
that are not active. If any of the storage objects that the specified
volume or storage object comprises are not active, they will be
activated so that the specified volume or storage object can be
activated.
The Activate command has the following syntax:
Activate : name
where
Activate
may be abbreviated as act.
name is the name of a volume or storage object.
Example:
Given a volume /dev/evms/mydata that is not active, activate the
volume.
act:/dev/evms/mydata
ADD FEATURE
The Add Feature command adds an EVMS feature to an existing EVMS native
volume. The feature is added to the volume by shrinking the filesystem
on the volume to make room for the metadata of the new feature. The
metadata are then written on the volume. In order to successfully
write the metadata for the feature on the volume, EVMS must have a
Filesystem Interface Module (FSIM) for the filesystem on the volume,
and the FSIM must support filesystem shrinking.
If the volume cannot be unmounted (perhaps because it is root), the
FSIM must support on-line shrinking of the filesystem. The filesystem
must be able to be shrunk by an amount that is equal to or larger than
the metadata of the feature.
CAUTION: The Add Feature command should not be used on volumes
that do not have a filesystem (such as databases) as data loss
may occur.
The add feature command has the following syntax:
Add Feature : feature = { [name = value [, name = value] ...] } ,
volume
where
Add Feature
may be abbreviated as af.
feature
is the name of the EVMS feature to add to the volume.
name is the name of an option accepted by the feature.
value is an acceptable value for the option name.
volume is the name of an EVMS volume to which the feature is added.
Example:
The following command adds the feature "My_Drive_Link" to the volume,
"My_EVMS_Volume."
af:DriveLink={Name=My_Drive_Link},/dev/evms/My_EVMS_Volume
ADD SEGMENT MANAGER
The Add Segment Manager command is used to assign a segment manager to
any disk or segment in the system that does not already have a Segment
Manager assigned to it.
The Add Segment Manager command has the following syntax:
Add Segment Manager : segment-mgr = { [name = value [, name = value]
...] } , disk
where
Add Segment Manager
can be abbreviated as asm.
segment-mgr
is the name of the segment manager that is to be assigned to a
disk.
name is the name of an option accepted by the segment manager.
value is an acceptable value for the option name.
disk is the name of the disk that the Segment Manager will be
assigned to.
The Add Segment Manager command is the same as the Assign command. See
the section for the Assign command for an example.
ALLOCATE
The Allocate command is used to allocate regions or segments from
blocks of freespace.
The Allocate command has the following syntax:
Allocate : freespace [, name = value] ...
where
Allocate
may be abbreviated as a.
freespace
is the name of a region or segment which represents freespace,
such as sdb_freespace1.
name is the name of an option accepted by the region manager or
segment manager which created freespace.
value is an acceptable value for the option name.
Example:
Given a disk with no partitions that is under the control of the DOS
Segment Manager, create a 50 MB segment in an extended partition. The
new segment does not have to be bootable.
a:sdb_freespace1,size=50MB,offset=0,primary=false,bootable=false
ASSIGN
The Assign command is used to assign a segment manager to any disk or
segment in the system that does not already have a Segment Manager
assigned to it.
The Assign command is the same as the Add Segment Manager command.
The Assign command has the following syntax:
Assign : segment-mgr = { [name = value [, name = value] ...] } , disk
where
Assign can be abbreviated as as.
segment-mgr
is the name of the segment manager that is to be assigned to a
disk.
name is the name of an option accepted by the segment manager.
value is an acceptable value for the option name.
disk is the name of the disk that the Segment Manager will be
assigned to.
Example:
You have installed a brand new disk into your computer. You wish to
partition this disk into multiple partitions using the DOS Segment
Manager and the standard Linux partitioning scheme. What must you do
before you can partition the disk?
You must assign the DOS Segment Manager to the disk. If EVMS
identifies the disk as sdb, the command to do this is:
as:DosSegMgr={TypeByName=Linux},sdb
The previous command will cause the DOS Segment Manager to assume
control of the disk sdb and prepare the disk for partitioning. Two new
storage objects will result from the Assign command: a metadata segment
object and a freespace segment object. The freespace segment,
sdb_freespace1, is created to represent the space available on sdb.
This space can be divided into data segments (partitions) using
Allocate or Create.
CHECK
The Check command performs a consistency check on the filesystem
contained within the specified volume. This command is the equivalent
of the Linux fsck command.
The Check command has the following syntax:
Check : volume [, name = value] ...
where
Check can be abbreviated as ch.
volume is the name of the volume with the filesystem to be checked.
name is the name of an option supported by the File System Interface
Module (FSIM) for the filesystem found on the specified volume.
value is an acceptable value for option name.
COMMIT
The Commit command can be used when the EVMS CLI is running in
alternate mode to force the CLI to save all changes since the last
save.
The Commit command is the same as the Save command.
The EVMS CLI can run in either of two modes: default or alternate. The
default mode writes to disk any changes made by a command immediately
after that command is executed. The alternate mode, which is invoked
by using the -c option on the command line that invoked the CLI, holds
all changes in memory until the CLI exits. Once the CLI exits, all of
the changes being held in memory are written to disk. This alternate
mode can significantly improve performance in situations where large
command files are executed or complex configurations are used.
However, it is not always desirable to hold all changes in memory until
the EVMS CLI exits.
When the EVMS CLI is operating in default mode, the Commit command does
nothing. When the EVMS CLI is operating in alternate mode, the Commit
command forces the EVMS CLI to save all changes it has accumulated.
This option effectively gives the user control over when changes are
saved and when they are held in memory.
The Commit command has the following syntax:
Commit [: Hold|Release]
where
Hold tells the EVMS CLI to hold all changes in memory and to commit
those changes to disk when the Interpreter exits.
Release
tells the EVMS CLI to write all pending changes to disk
immediately and write changes to disk after each command has
been completed.
COMMIT WITH THE HOLD KEYWORD
Example:
The EVMS CLI is operating it its default mode, with changes being
committed to disk after each command. Change the Interpreter’s mode of
operation so that changes are held in memory until the Interpreter
exits.
commit:hold
COMMIT WITH THE RELEASE KEYWORD
Example:
The EVMS CLI is operating in its alternate mode, with all changes being
held in memory until the EVMS CLI exits. Change the EVMS CLI’s mode of
operation so that changes are committed to disk after each command and
write to disk all changes that are currently being held in memory.
commit:release
COMMIT IN ALTERNATE MODE
Example:
The EVMS CLI is operating in its alternate mode, with all changes being
held in memory until the EVMS CLI exits. Without changing the mode the
Interpreter operates in, force the Interpreter to commit to disk all
the changes it is currently holding in memory.
commit
CONVERT
The Convert command has two forms. The first form converts an existing
compatibility volume into an EVMS volume. The second form converts an
EVMS volume into a compatibility volume.
CONVERTING FROM COMPATIBILITY VOLUMES TO EVMS VOLUMES
The Convert command converts an existing compatibility volume into an
EVMS volume by adding EVMS metadata to the compatibility volume. If
the compatibility volume does not contain a filesystem, EVMS can add
its metadata to the volume and convert it. If the compatibility volume
contains a filesystem, EVMS shrinks the filesystem to make room for the
EVMS metadata. EVMS must have a filesystem interface module (FSIM)
that corresponds to the compatibility volume’s filesystem, and the FSIM
must support filesystem shrinking.
CAUTION: The Convert command should not be used on compatibility
volumes that are being used without a filesystem (for example,
databases) as data loss may occur.
The Convert command has the following syntax when converting a
compatibility volume to an EVMS volume:
Convert : volume , Name = new-name
where
Convert
may be abbreviated as co.
volume is the name of the compatibility volume to be converted into an
EVMS volume
Name may be abbreviated as the single letter n.
new-name
is the new name for the volume. Please note that the new volume
names must be in quotation marks if they contain spaces or any
non-alphanumeric characters.
Example:
The following command changes volume /dev/evms/hda3 into an EVMS volume
named New_EVMS_Volume.
Co : /dev/evms/hda3 , N = New_EVMS_Volume
CONVERTING FROM EVMS VOLUMES TO COMPATIBILITY VOLUMES
The Convert command converts an existing EVMS volume into a
compatibility volume by removing any EVMS metadata on the volume.
Currently, this conversion can only occur for EVMS volumes that have no
features applied to them.
The Convert command has the following syntax when attempting to convert
an EVMS volume into a compatibility volume:
Convert : volume, Compatibility
where
Convert
may be abbreviated as Co.
volume is the name of the EVMS volume to be converted into a
compatibility volume.
Compatibility
is the EVMS keyword used to indicate that a compatibility volume
is the type of the resulting volume. Compatibility may be
abbreviated as the single letter c.
Example:
The following command changes EVMS volume /dev/evms/Data to a
compatibility volume.
Co : /dev/evms/Data , C
CREATE
The Create command is used to create containers, EVMS objects, regions,
segments, and volumes. The different items the Create command
generates can also be abbreviated as a single letter on the command
line.
The syntaxes for each of the Create command options are listed below:
CREATING CONTAINERS
Create : Container , plug-in = { [name = value [, name = value] ...] }
, object [, object] ...
where
Create can be abbreviated as c.
Container
can be abbreviated as c.
plug-in
is the name of the plug-in to use when creating the container.
name is the name of an option accepted by the plug-in.
value is an acceptable value for the option name.
object is the name of a storage object used in the creation of the
container.
Example:
Given a system with three available hard drives (sdc, sdd, hdc), use
the EVMS LVM Region Manager to combine these disks into a container
called Sample_Container with a PE (physical extent) size of 16MB.
c:c,LvmRegMgr={name=Sample_Container,pe_size=16MB},sdc,sdd,hdc
CREATING EVMS OBJECTS
Create : Object , feature = { [name = value [, name = value] ...] } ,
object [, object] ...
where
Create can be abbreviated as c.
Object can be abbreviated as o.
feature
is the name of the EVMS Feature plug-in to use when creating the
EVMS object.
name is the name of an option accepted by the region manager.
value is an acceptable value for the option name.
object is the name of a region, segment, disk, or EVMS object to be
used in the creation of the new EVMS object.
Example:
Given a system with a volume /dev/evms/Source, and an available segment
sdb5, create a snapshot object called "My_Snapshot_Object" using the
EVMS SnapShot feature. /dev/evms/Source is the source of the snapshot,
and sdb5 is the backing store for the snapshot.
c:o,Snapshot={original=/dev/evms/Source,snapshot=My_Snapshot_Object},sdb5
CREATING REGIONS
Create : Region , region-mgr = { [name = value [, name = value] ...] }
, object [, object] ...
where
Create can be abbreviated as c.
Region can be abbreviated as r.
region-mgr
is the name of the Region Manager plug-in you want to use.
name is the name of an option accepted by the region manager.
value is an acceptable value for the option name.
object is the name of a region, segment, or disk to be used in the
creation of the new region.
CREATING SEGMENTS
Create : Segment , freespace [, name = value] ...
where
Create can be abbreviated as c.
Segment
can be abbreviated as s.
freespace
is the name of a segment representing freespace.
name is the name of an option accepted by the segment manager that
created the freespace.
value is an acceptable value for the option name.
Example:
Given a disk that is under the control of the DOS Segment Manager, has
no primary partitions, and has a 200 MB freespace segment called
sdb_freespace1, create a 50 MB logical segment. The new segment does
not have to be bootable.
c:s,sdb_freespace1,size=50MB,offset=0,primary=false,bootable=false
CREATING COMPATIBILITY VOLUMES
Create : Volume , object , Compatibility
where
Create can be abbreviated as c.
Volume can be abbreviated as v.
object is the name of the disk, segment or region that will become a
volume.
Example:
Given a system with an unused segment sda3, turn this segment into a
compatibility volume.
c:v,sda3,c
CREATING EVMS VOLUMES
Create : Volume , object , Name = name
where
Create can be abbreviated as c.
Volume can be abbreviated as v.
object is any disk, segment, region, or EVMS object that is not already
a volume or a part of a volume, storage object, or storage
container.
name is the name that you would like the volume to have. This name
must be unique throughout the system, and the volume, once
created, will be known as /dev/evms/name.
Example:
Given a system with an unused segment sda3, make sda3 an EVMS volume
known as Widow_Maker.
c:v,sda3,n=Widow_Maker
DEACTIVATE
The Deactivate command is used to deactivate volumes or storage objects
that are active. When a storage object is deactivated, all of the
storage objects and volumes that are built using the specified storage
object will also be deactivated, since active objects and volumes
cannot be built from inactive objects.
The Deactivate command has the following syntax:
Deactivate : name
where
Deactivate
may be abbreviated as deact.
name is the name of a volume or storage object.
Example:
Given a volume /dev/evms/mydata that is active, deactivate the volume.
deact:/dev/evms/mydata
DELETE
The Delete command deletes a volume, container EVMS object, region, or
segment from the system.
The Delete command has the following form:
Delete : name
where
Delete can be abbreviated as d.
name is the name of the volume, container, EVMS object, region, or
segment that is to be deleted.
ECHO
The Echo command echoes a string to the standard output. Echo allows
the user to output user defined text from an EVMS command file.
The Echo command has the following syntax:
Echo : String
where
String is any sequence of ASCII characters except quotation marks. A
string should be enclosed in quotation marks if it contains any
non-alphabetic or non-numeric characters or spaces. If a
quotation mark is embedded in the string as part of the string,
then quotation marks should also surround the embedded string,
as in the example below:
Example:
Echo : "This is a ""sample"" string with embedded quotation marks."
EXIT
The Exit command is used to exit the EVMS CLI.
The Exit command is the same as the Quit command.
EXPAND
The Expand command is used to increase the size of a volume, storage
container, or storage object.
Listed below are the two syntaxes of the expand command. The first
syntax is for increasing the size of storage containers. The second
syntax of Expand is for increasing the size of volumes and storage
objects.
Increasing the Size of a Storage Container
Storage Containers are expanded by adding segments or regions to them.
When expanding containers, the Expand command has the following syntax:
Expand : container , object [, object] ...
where
Expand can be abbreviated as e.
container
is the name of the container to expand.
object is the name of a disk. segment or region to add to the container
specified by container.
Increasing the Size of a Volume or Storage Object
An EVMS volume or storage object can be comprised of one or more EVMS
objects, regions, segments, or disks. Whether a volume or storage
object can be expanded or not depends on how it is constructed. For
example, if a volume consists of a single segment with no EVMS features
applied to it, then it can only be expanded if the Segment Manager that
created the segment can increase the size of that segment. EVMS allows
complete control over how a volume is expanded.
A more complicated volume may have several ways to expand. For
example, a volume created from several segments using EVMS Drive
Linking can be expanded by increasing the size of the last segment in
the drive link. You can also expand the volume by using EVMS Drive
Linking to add another segment to the volume. When a volume can be
expanded in multiple ways, we say that the volume has multiple
expansion points.
To expand a volume, you must specify which expansion point to use. The
same is true for storage objects. In the example from the paragraph
above, there are two expansion points. One expansion point is the EVMS
object created by EVMS Drive Linking. This EVMS object could be
expanded by adding another segment to it. The second expansion point
is the last segment used in the EVMS object formed by EVMS Drive
Linking. While the other segments used to create this EVMS object may
be capable of being expanded, EVMS Drive Linking allows only the last
segment to be expanded.
To find the expansion points for a storage object or volume, use the
Query Expand Points command. Once you know the expansion points for a
volume or storage object, these points can be used to expand the volume
or storage object.
When increasing the size of a volume or storage object the Expand
command has the following syntax:
Expand : expansion-point [, name = value] ... [, object] ...
where
Expand can be abbreviated as e.
expansion-point
is the name of an expansion point as provided by the Query
Expand Points command.
name is the name of an option supported by the plug-in module that
controls Expansion-Point.
value is an acceptable value for the option Name.
object is the name of an acceptable EVMS object, region, segment,
freespace, or disk to use for expanding the volume.
Example:
This example assumes that there is a volume created from three segments
using EVMS Drive Linking. The three segments are sda1, sdb1, and sdc1.
The EVMS object created by EVMS Drive Linking is called DL1, and the
volume is called /dev/evms/Sample_Volume. The segment sdc1 is
controlled by the DOS Segment Manager (DosSegMgr), and has a 50 MB
block of freespace (sdc_freespace1) adjacent to it on the disk. Also,
there is an unused 200 MB segment known as hda7 available in the
system. The Query Expand Points command indicates that this volume has
two expansion points: DL1 and sdc1. Expand this volume by 250 MB.
First, we must consider the order in which we will use the expand
points to expand the volume. Currently, sdc1 is an expand point.
Since EVMS Drive Linking allows only the last segment it is linking to
be expanded, sdc1 must be the last segment that EVMS Drive Linking uses
to create DL1. If we add hda7 to DL1, then hda7 will become the last
segment used in DL1, and sdc1 will not be an expansion point anymore.
Without being able to expand sdc1, we will not be able to reach our
goal of expanding the volume by 250 MB. However, expanding sdc1 has no
effect on our ability to add hda7 to DL1, so if we expand sdc1 before
we add hda7 to DL1, we will be able to achieve our goal of expanding
the volume by 250 MB. Completing our expansion will require two
commands. First, to expand sdc1, we use:
e:sdc1,size=50MB,sdc_freespace1
Now, to add hda7 to DL1, use the command:
e:DL1,hda7
The resulting change is that the volume is 250 MB larger than before.
FORMAT
The Format command creates a filesystem on a volume. This is the
equivalent of the Linux mkfs command.
The Format command is the same as the Mkfs command.
The Format command has the following syntax:
Format : FSIM = { [name = value [, name = value] ...] } , volume
where
Format can be abbreviated as f.
FSIM is the name of a File System Interface Module recognized by
EVMS. The specified FSIM is used to create the filesystem on
the volume specified by volume. Normally there is one FSIM for
each filesystem, so specifying the FSIM is the same as
specifying the filesystem. In cases where one FSIM supports
more than one filesystem, you can use an option to specify which
filesystem should be created.
name is the name of an option supported by the FSIM for the
filesystem found on the specified volume.
value is an acceptable value for the option Name.
volume is the name of the volume where the filesystem is to be created.
HELP
The CLI offers help on the essential commands. To obtain detailed help
on an EVMS command, type the following:
Help : command
The CLI supports the following commands:
Activate
activates volumes and storage objects.
Add Feature
adds the specified feature to an existing EVMS volume.
Add Segment Manager
attempts to add the specified segment manager to a disk or
segment. (Same as Assign.)
Allocate
allocates regions and segments from freespace.
Assign assigns a segment manager to a disk or segment. (Same as Add
Segment Manager.)
Check performs an fsck on a volume.
Commit causes any changes that have not yet been written to disk to be
written to disk. (Same as Save.)
Convert
converts a compatibility volume into an EVMS volume or an EVMS
volume into a compatibility volume.
Create creates volumes, EVMS objects, regions, segments, and
containers.
Deactivate
deactivates volumes and storage objects.
Delete deletes volumes, containers, EVMS objects, regions, and
segments.
Echo echoes a string to standard output.
Exit exits the EVMS CLI. (Same as Quit.)
Expand expands the size of volumes, containers, EVMS objects, regions,
and segments.
Format performs a mkfs operation on a volume. (Same as Mkfs.)
Help provides help on a specific EVMS command.
Mkfs creates a filesystem on a volume. (Same as Format.)
Modify modifies some of the options associated with a container, EVMS
object, region, segment, or disk.
Mount mounts a volume on a directory.
Probe causes EVMS to check the system for hardware changes.
Query gathers information about the volumes, containers, EVMS objects,
regions, and segments in the system.
Quit exits the EVMS CLI. (Same as Exit.)
Remove removes the segment manager assigned to a disk or segment.
Rename changes the names of volumes.
Replace
replace a storage object with another storage object.
Revert deconstructs a volume or storage object a layer at a time.
Save causes any changes which have not yet been written to disk to be
written to disk. (Same as Commit.)
Set modifies some of the options associated with a container, EVMS
object, region, segment, or disk.
Shrink reduces the size of volumes, containers, EVMS objects, regions,
and segments.
Task allows access to plug-in specific functions.
Unformat
removes a filesystem from a volume. The contents of the
filesystem are lost.
UnMkfs removes a file system from a volume. The contents of the volume
are lost.
Unmount
unmounts a volume.
Example:
Get detailed help on the Create command.
Help: Create
MKFS
The mkfs command creates a filesystem on a volume.
The Mkfs command is the same as the Format command.
The mkfs command has the following syntax:
mkfs : FSIM = { [name = value [, name = value] ...] } , volume
where
FSIM is the name of a File System Interface Module recognized by
EVMS. The specified FSIM is used to create the filesystem on
the volume specified by volume. Normally there is one FSIM for
each filesystem, so specifying the FSIM is the same as
specifying the filesystem. In cases where one FSIM supports
more than one filesystem, you can use an option to specify which
filesystem should be created.
name is the name of an option supported by the FSIM for the
filesystem found on the specified volume.
value is an acceptable value for the option name.
volume is the name of the volume where the filesystem is to be created.
MODIFY
The Modify command changes options on EVMS objects, regions,
containers, segments, or disks. If a Query command which returns EVMS
objects, regions, containers, segments, or disks is executed using the
List Options pseudo filter, then the changeable options for each item
returned will be listed with that item.
The Modify command has the following syntax:
Modify : item , name = value [, name = value] ...
where
item is the name of a EVMS object, region, container, segment or disk
whose options are to be changed.
name is the name of an option that can be set for item.
value is an acceptable value for option name.
MOUNT
The Mount command mounts a volume on a directory.
The Mount command has the following syntax:
Mount : volume , mount-point [, mount-options]
where
volume is the name of the volume to be mounted.
mount-point
is the name of the directory on which to mount the volume.
mount-options
is a string of options to be passed to the mount command.
PROBE
The Probe command is used to probe the system for hardware changes.
This command is useful when the media in a removable media device has
been changed. The Probe command will commit any pending changes (from
prior commands) to disk before probing the system for hardware changes,
even if the -c option was used when invoking the CLI. Probe can be
abbreviated as a single letter p on the command line.
QUERY
The Query command is used to obtain information about the states of the
volumes, EVMS objects, regions, containers, segments, and disks in the
system.
The Query command has several different syntaxes. One syntax is used
for gathering information about the volumes, EVMS objects, regions,
containers, segments, disks, and plug-in modules in the system. The
other syntax for the Query command is used for gathering information
related to various tasks that you can perform on items in the system.
To gather information about volumes, containers, EVMS objects, regions,
segments, disks, or plug-in modules, use this syntax of the Query
command:
Query : data-type [, filter] ...
where
Query can be abbreviated as the single letter q.
data-type
is either:
plug-ins
(abbreviated as p)
volumes
(abbreviated as v)
containers
(abbreviated as c)
objects
(abbreviated as o)
regions
(abbreviated as r)
segments
(abbreviated as s)
disks (abbreviated as d)
filter is one of the available filters for the type of data being
returned. A filter restricts what is returned based upon some
characteristic of the items being returned. The available
filters for a query depend upon data-type.
When processing a query like the one above, the CLI gathers items in
the system of data-type. The interpreter puts these items into a list
called the Return Values List. Each of the filters you specified
examines the Return Values List and removes any items that do not fit
the filter criteria. Once all of the filters have processed the Return
Values List, the CLI displays the items that remain in the Return
Values List.
NOTE: Not all filters will work with every query. Furthermore,
some filters may be mutually exclusive. See the EVMS Command
Line Grammar to determine which combinations of filters are
allowed for a particular query.
SUPPORTED FILTERS
The EVMS Command Line Interpreter supports the following filters:
Plug-in Type Filter
The plug-in Type filter is only available when data-type is
equal to plug-ins. This filter removes from the Return Values
List any entries for plug-in modules that are not of the type
specified.
The syntax for this filter is:
Type = plugin-type
where
Type can be abbreviated as the single letter t.
plugin-type
is one of the following:
device manager
(abbreviated as d)
segment manager
(abbreviated as s)
region manager
(abbreviated as r)
feature
(abbreviated as f)
filesystem interface module
(abbreviated as FSIM)
cluster management
(abbreviated as CM)
Plugin Filter
The Plugin filter is available when data-type is either volumes,
objects, regions, containers, segments, disks, or plug-ins.
This filter removes any entries that have no association with
the specified plug-in module from the Return Values List.
· For volumes and storage objects, any volume that was created
without the use of the specified plug-in module is removed
from the Return Values List.
· For regions, any region not created by the specified plug-in
module is removed from the Return Values List.
· For containers, any container not created by the specified
plug-in module is removed from the Return Values List.
· For segments, any segment not created by the specified plug-in
module is removed from the Return Values List.
· For disks, any disk not claimed by the specified plug-in
module is removed from the Return Values List.
· For plug-in modules, all plug-in modules other than the one
specified are removed from the Return Values List.
The syntax of the Plugin filter is:
Plugin = plug-in
where
Plugin can be abbreviated as the single letter p.
plug-in
is the name or ID number of a plug-in module.
Volume Filter
The Volume filter is available when data-type is either plug-
ins, objects, regions, segments, or disks. This filter removes
from the Return Values List any item that was not used in the
construction of the specified volume.
The syntax for the Volume filter is:
Volume = volume
where
Volume can be abbreviated as the single letter v.
volume is the fully qualified name of a volume.
Object Filter
The Object filter is available when data-type is either plug-
ins, volumes, objects, regions, segments, or disks. This filter
removes from the Return Values List items that either did not
create the specified object, or were created without using the
specified storage object. The Object filter removes from the
Return Values List each of the following:
· For plug-ins, the filter removes all plug-in modules except
for those that are needed to create the specified storage
object.
· For volumes, the filter removes any volume that does not use
the specified storage object.
· For objects, regions, segments, and disks, the filter removes
any storage object that was not used in the creation of the
specified storage object.
The syntax of the Object filter is:
Object = name
where
Object can be abbreviated as the single letter o.
name is the name of an object that EVMS has discovered.
Container Filter
The Container filter is available when data-type is either
plugins, volumes, objects, regions, or segments.
The list below explains what the Container filter removes from
the Return Values List when data-type is one of the following:
· For plug-ins, the filter removes all plug-ins that were not
used to create the container.
· For volumes, the filter removes any volume constructed without
using a region from the specified container.
· For objects, the filter removes any object constructed without
using a region from the specified container.
· For regions, the filter removes any regions that do not come
from the specified container.
· For segments, the filter removes any segment that was not used
to create the container.
The syntax of the Container filter is:
Container = name
where
Container
can be abbreviated as the single letter c.
name is the name of a container that EVMS has discovered.
Region Filter
The Region filter is available when data-type is either volumes,
objects, or containers.
The list below explains what the Region filter removes from the
Return Values List when data-type is one of the following:
· For volumes, this filter removes any volume constructed
without using the specified region.
· For objects, this filter removes any object constructed
without using the specified region.
· For containers, this filter removes any container other than
the one it came from.
The syntax of the Region filter is:
Region = name
where
Region can be abbreviated as the single letter r.
name is the name of a region that EVMS has discovered.
Disk Filter
The Disk filter is available when data-type is segments. This
filter removes from the Return Values List any segment which
does not lie on the specified disk.
The syntax of the Disk filter is:
Disk = name
where
Disk can be abbreviated as the single letter d.
name is the name of a disk that EVMS knows about.
Size Filters
There are three size filters: less than, greater than, and equal
to. These filters are available when data-type is either
volumes, containers, objects, regions, segments, or disks.
These filters remove items from the Return Values List based
upon their size.
The Less Than filter has the following syntax:
LT n unit
where
n is a positive integer or 0.
unit is either KB, MB, GB, or TB.
The Greater Than filter has the following syntax:
GT n unit
where
n is a positive integer or 0.
unit is either KB, MB, GB, or TB.
The Equal filter has the following syntax:
EQ n unit , precision
where
n is a positive integer or 0.
unit if specified, must be either KB, MB, GB, or TB.
precision
is a positive integer. precision indicates how "sloppy"
a match to make. If no unit is specified, then precision
is interpreted to be a percentage. If precision is seen
as a percentage, the value is considered to be equal to n
as long as the value is within n plus or minus precision
percent of n. If a unit (KB, MB, GB, TB) is specified
for precision, then a value is considered equal to n if
the value is within the range of n - precision to n +
precision.
Freespace Filter
The Freespace filter removes any items that do not contain
freespace from the Return Values List. This filter is only
useable when data-type is containers.
The syntax of the Freespace filter is:
Freespace , size-filters
where
Freespace
can be abbreviated as the single letter f.
size-filters
These filters are the same Size filters used with other
filters, only now, instead of using the size of the
containers for comparisons, the size-filters will use the
freespace in the containers for comparisons.
Expandable Filter
The Expandable filter is available when data-type is either
volumes, regions, objects, or segments. This filter removes any
items that cannot be expanded from the Return Values List.
The syntax of this filter is:
Expandable
where
Expandable
can be abbreviated as the single letter e.
Shrinkable Filter
The Shrinkable filter is available when data-type is either
volumes, regions, objects, or segments. This filter removes any
items that cannot be shrunk from the Return Values List.
The syntax of this filter is:
Shrinkable
where
Shrinkable
can be abbreviated as the single letter s.
Unclaimed Filter
The Unclaimed filter is available when data-type is disks. This
filter removes all disks which have been claimed by a Segment
Manager plug-in module (disks that have a recognized
partitioning scheme in place) from the Return Values List. The
disks left in the Return Values List will either have no
partitioning scheme, or the partitioning scheme is unrecognized.
The syntax of this filter is:
Unclaimed
where
Unclaimed
can be abbreviated as the single letter u.
List Options Pseudo Filter
List Options is treated like a filter, but it actually causes
the CLI to list what can be done with each item in the Return
Values List.
The syntax of this filter is:
List Options
where
List Options
can be abbreviated with the letters lo.
SAMPLE QUERIES USING FILTERS
· To query the plug-ins in the system and their options:
q:p,lo
· To query only the region manager plug-ins in the system and their
options:
q:p,t=r,lo
· To query the volumes in the system:
q:v
· To query the volumes in the system over 1GB in size:
q:v,gt 1GB
· To query the storage objects in the system:
q:o
· To query the segments in the system that reside on disk sda:
q:s,d=sda
· To query the segments in the system that belong to the container
lvm/MyStuff, are over 500 MB in size and less than 2 GB in size, and
come from disk sda:
q:s,c=lvm/MyStuff,GT 500MB,lt 2GB,d=sda
SPECIALTY QUERY COMMANDS
The following commands allow for specialty queries.
Query Children
The Query Children command returns items that were used to
create the specified item. For example, the children of a
storage object are the EVMS objects, regions, disks, or segments
that were used to create the specified storage object.
The syntax of this command is:
Query : Children , name
where
Children
can be abbreviated as chi.
name is the name of a volume, EVMS object, region, segment, or
container.
Query Parent
The Query Parent command returns the item (if there is one) that
uses the specified item. For example, if a storage object is
specified, then this command will return the volume or storage
object which was created using the specified storage object, if
such a volume or storage object exists. The syntax of this
command is:
Query : Parent , name
where
Parent can be abbreviated as par.
name is the name of a storage object, region, segment,
container, or disk.
Query Expand Points
The Query Expand Points returns the expansion points for a
volume or storage object. The expansion points for a volume or
storage object are those entities within the volume or storage
object that can be expanded without causing a loss of data.
The syntax of this command is:
Query : Expand Points , name
where
Expand Points
can be abbreviated as ep.
name is the name of a storage object or volume.
Query Shrink Points
Query Shrink Points returns the shrink points for a volume or
storage object. The shrink points for a volume or storage
object are those entities within the volume or storage object
that can be shrunk without causing a loss of data. The syntax
of this command is:
Query : Shrink Points , name
where
Shrink Points
can be abbreviated as sp.
name is the name of a Storage Object or Volume.
Query Extended Info
Query Extended Info command allows access to any additional
information that may be available for a plug-in module, a EVMS
object, a region, a segment, a disk, or a container. The syntax
of this command is:
Query : Extended Info , name [, field]
where
Extended Info
can be abbreviated as ei.
name is the name of a EVMS object, disk, region, segment,
container, or plug-in module. It can also be the numeric
ID of a plug-in module.
field is the name of a specific piece of extended information.
Extended Information is grouped into fields. Each field
has a name and one or more values associated with it.
Query Acceptable
The Query Acceptable allows you to discover which EVMS objects,
regions, segments, or disks are acceptable for creating or
expanding a volume, EVMS object, region, or segment. The
command works as follows:
When you create containers, objects, or regions, specify the
following: the plug-in module being used, the values for the
options that the plug-in module is to use when creating the
container/object/region, and the EVMS objects, regions,
segments, or disks that you have decided to use. The query will
return any EVMS objects, regions, segments, or disks that are
still available and acceptable for use in creating the
container/object/region.
Example:
An example of using this command would be to determine
what segments should be used to create a software RAID 5
storage object. Initially, no segments have been
selected, so all unused segments in the system might be
available and might be returned by this query. Choose an
initial segment, which causes all segments on the same
drive to not be acceptable anymore.
To find out what segments are still available, use this
query again and specify the segments that have already
been chosen. This query will return all of the segments
that might still be chosen. To see which segments are
still available, choose another segment, and use this
query again, specifying all of the segments that have
already been chosen in the order in which they were
chosen. You can use this iterative process to build an
ordered list of segments. From this list you can see
what segments you can use in an actual create command to
create the desired software RAID 5 storage object.
When expanding volumes or storage objects, specify the volume or
storage object to be expanded along with any EVMS objects,
segments, regions, or disks that you have already chosen to use
in the expansion. This query will return the EVMS objects,
regions, segments, or disks that you can still select and use to
expand the specified volume or storage object.
As described above, an iterative process can be used to build an
ordered list of the EVMS objects, regions, segments, or disks
that can be used to expand the specified volume or storage
object with an actual expand command.
The Query Acceptable command has two syntaxes: one for use with
Create, the other for use with Expand.
Create
For determining what is acceptable for use with
Create, use the following syntax:
Query : Acceptable, Create , type, plug-in = {
[name = value [, name = value] ...] } , object
[, object] ...
where
Acceptable
can be abbreviated as the single letter a.
Create can be abbreviated as the single letter c.
type is either object, region, or container.
object can be abbreviated as a single
letter o. region can be abbreviated as a
single letter r. container can be
abbreviated as a single letter c.
plug-in
is the name or ID number of the plug-in
module to use when creating type.
name is the name of an option supported by
plug-in.
value is a legitimate value for the option name.
object is the name of a EVMS object, region,
segment or disk which is to be used to
create type.
Expand
For determining what is acceptable for use with
Expand, use the following syntax:
Query : Acceptable , Expand , expansion-point ,
object [, object] ...
where
Acceptable
can be abbreviated by the single letter a.
Expand can be abbreviated by the single letter e.
expansion-point
is the name of a volume or storage object
that is to be expanded.
object is the EVMS name of a EVMS object, region,
segment or disk which is to be used when
expanding expansion-point.
QUIT
The Quit command is used to exit the EVMS CLI.
The Quit command is the same as the Exit command.
REMOVE
The Remove command is used to remove a segment manager from a disk. A
segment manager can only be removed from a disk when all of the data
segments on that disk have been deleted. The Remove command causes a
Segment Manager to remove its metadata from the disk, thereby leaving
an empty disk. The empty disk can be used directly, or another segment
manager can be assigned to it.
The Remove command has the following syntax:
Remove : name
where
Remove can be abbreviated as rem.
name is the name of a disk that EVMS knows about.
Example:
This example will assume that you have a disk, sdb, and that this disk
has several partitions on it that are managed by the DOS Segment
Manager. The data segments on disk sdb are not being consumed by any
EVMS object and could be deleted. Assume that you have a drive link
that is aggregating several disks and that you would like to expand the
drive link with the addition of disk sdb. In order for disk sdb to
become an acceptable object for expanding the drive link, you must
remove the segment manager and all the partitions from the disk.
After deleting all the data segments on disk sdb, use the following
command:
Rem:sdb
RENAME
The Rename command is used to change the name of an EVMS volume.
The Rename command has the following syntax:
Rename : volume , Name = new-name
where
Rename can be abbreviated as the single letter r.
volume is the name of the volume that needs to be changed.
Name can be abbreviated as the single letter n.
new-name
is the new name for the volume. Please note that the new volume
name must be in quotation marks if it contains spaces or any
non-alphanumeric characters.
Example:
Rename the volume /dev/evms/John to /dev/evms/Fred.
r:/dev/evms/John,n=Fred
REVERT
The Revert command strips away the topmost layer of an EVMS volume or
storage object and restores it to its previous EVMS state. Thus, an
EVMS Volume will revert to the EVMS Storage Object that it came from.
The Revert command has the following syntax:
Revert : name
where
Revert can be abbreviated as rev.
name is the name of the volume or storage object to revert.
Example:
In this example, assume that you have just created a storage object
named "Fred" from a storage object named "Barney." Fred is a
complicated storage object that would take time to recreate. However,
after creating Fred, you find out that you applied the wrong feature to
Barney to create Fred. To remove the feature that was applied to
Barney to create Fred without having to delete Fred and start from
scratch, type the following command:
Rev:Fred
The Revert command will strip away the top most feature on Fred undoing
the creation of Fred and leaving Barney.
SAVE
The Save command can be used when the EVMS CLI is running in alternate
mode to force the CLI to save all changes since the last save.
The Save command is the same as the Commit command.
The EVMS CLI can run in either of two modes: default or alternate. The
default mode writes to disk any changes made by a command immediately
after that command is executed. The alternate mode, which is invoked
by using the -c option on the command line that invoked the CLI, holds
all changes in memory until the CLI exits. Once the CLI exits, all of
the changes being held in memory are written to disk. This alternate
mode can significantly improve performance in situations where large
command files are executed or complex configurations are used.
However, it is not always desirable to hold all changes in memory until
the EVMS CLI exits.
When the EVMS CLI is operating in default mode, the Save command does
nothing. When the EVMS CLI is operating in alternate mode, the Save
command forces the EVMS CLI to save all changes it has accumulated.
This option effectively gives the user control over when changes are
saved and when they are held in memory.
The Save command has the following syntax:
Save [: Hold|Release]
where
Hold tells the EVMS CLI to hold all changes in memory and to save
those changes to disk when the Interpreter exits.
Release
tells the EVMS CLI to write all pending changes to disk
immediately and write changes to disk after each command has
been completed.
SAVE WITH THE HOLD KEYWORD
Example:
The EVMS CLI is operating it its default mode, with changes being saved
to disk after each command. Change the Interpreter’s mode of operation
so that changes are held in memory until the Interpreter exits.
save:hold
SAVE WITH THE RELEASE KEYWORD
Example:
The EVMS CLI is operating in its alternate mode, with all changes being
held in memory until the EVMS CLI exits. Change the EVMS CLI’s mode of
operation so that changes are saved to disk after each command and
write to disk all changes that are currently being held in memory.
save:release
SAVE IN ALTERNATE MODE
Example:
The EVMS CLI is operating in its alternate mode, with all changes being
held in memory until the EVMS CLI exits. Without changing the mode the
Interpreter operates in, force the Interpreter to save to disk all the
changes it is currently holding in memory.
save
SET
The Set command changes options on EVMS objects, regions, containers,
segments, or disks. If a Query command which returns EVMS objects,
regions, containers, segments, or disks is executed using the List
Options pseudo filter, then the changeable options for each item
returned will be listed with that item.
The Set command has the following syntax:
Set : item , name = value [, name = value] ...
where
item is the name of a EVMS object, region, container, segment or disk
whose options are to be changed.
name is the name of an option that can be set for item.
value is an acceptable value for option name.
SHRINK
The Shrink command reduces the size of a volume, storage object, or
storage container.
Reducing the Size of a Storage Container
You can reduce the size of a storage container by removing one or more
of the segments or regions it contains.
The Shrink command has the following syntax when used with storage
containers:
Shrink : container , object [, object] ...
where
Shrink can be abbreviated as the letter s.
container
is the name of the storage container to shrink.
object is the name of a segment or region in the storage container that
is to be removed from the storage container.
Reducing the Size of a Volume or Storage Object
An EVMS volume or storage object can be comprised of one or more EVMS
objects, regions, segments, or disks. Whether or not a volume or
storage object can be shrunk depends upon how it is constructed. For
example, if a volume consists of a single segment with no EVMS features
applied to it, then whether or not you can shrink the volume depends
upon whether the segment manager that created that segment can decrease
the size of that segment.
You can shrink a more complicated volume in several ways. For example,
you can shrink a volume created from several segments using EVMS Drive
Linking by decreasing the size of one of the segments being linked.
You could also use EVMS Drive Linking to remove a segment from the
drive link. If you could do both options to shrink the volume, we say
that the volume has multiple shrink points, because there are multiple
ways in which the volume can be shrunk.
EVMS gives you control over how a volume is shrunk. To shrink a
volume, you need to specify which shrink point to use. The same is
true for storage objects. If there are two shrink points, the first
would be the EVMS object created by EVMS Drive Linking. This storage
object could be shrunk by removing a segment from it. The second
shrink point would be the last segment used in the EVMS object formed
by EVMS Drive Linking. While you might be able to shrink the other
segments used to create this EVMS object, EVMS Drive Linking prohibits
shrinking these segments.
To find the shrink points for a storage object or volume, use the Query
Shrink Points command. Once the shrink points for a volume or storage
object are known, they can be used with this command to shrink the
volume or storage object.
The Shrink command has the following syntax:
Shrink : shrink-point [, name = value] ... [, object] ...
where
shrink-point
is the name of a shrink point as provided by the Query Shrink
Points command.
name is the name of an option supported by the plug-in module that
controls shrink-point.
value is an acceptable value for option name
object is the name of an acceptable EVMS object, region, segment, or
disk to be shrunk or removed from the volume.
Example:
This example assumes that you have a volume created from three segments
using EVMS Drive Linking. The three segments used are sda1, sdb1, and
sdc1. The EVMS object created by EVMS Drive Linking is called DL1, and
the volume is called /dev/evms/Sample_Volume. The segment sdc1 is
controlled by the DOS Segment Manager (DosSegMgr), and it can be shrunk
by 50 MB. The Query Shrink Points command returns DL1 and sdc1 as the
available shrink points. Shrink the volume by 50 MB.
s:sdc1,size=50MB,sdc1
TASK
The Task command accesses functions specific to an EVMS plug-in module.
The Task command can be used directly on an EVMS plug-in module, or it
can be used on a volume, EVMS object, region, segment, or container.
When used on a EVMS object, region segment, or container, the command
is directed to the plug-in module that owns the EVMS object, region,
segment, or container. When used on a volume, the command is directed
to the File System Interface Module associated with the volume.
The Task command has the following syntax:
Task : task-name , target [, name = value] ... [, source] ...
where
task-name
is the name of the task as defined by the EVMS plug-in that is
expected to perform the task.
target is the volume, object, region, segment, container, or plug-in
that the task is to be performed on.
name is the name of an option accepted by the plug-in that controls
the specified target.
value is an acceptable value for option name.
source is the name of a volume, object, region, segment to use when
performing the specified task on the specified target.
UNFORMAT
The Unformat command destroys the filesystem within the specified
volume. This process is typically completed by overwriting the
metadata for the filesystem with zeros. All data on the filesystem is
lost.
The Unformat command has the following syntax:
Unformat : volume
where
Unformat
can be abbreviated by the single letter u.
volume is the name of the volume whose filesystem is to be destroyed.
UNMKFS
The Unmkfs command destroys the filesystem within the specified volume.
This process is typically completed by overwriting the metadata for the
filesystem with zeros. All data on the filesystem is lost.
The Unmkfs command has the following syntax:
Unmkfs : volume
where
Unmkfs can be abbreviated by the single letter u.
volume is the name of the volume whose filesystem is to be destroyed.
UNMOUNT
The Unmount command unmounts a volume.
The Unmount command has the following syntax:
Unmount : volume
where
volume is the name of the Volume to be unmounted.
09 June 2005 EVMS(8)