evms(8)

NAME

evms - The evms command starts the Enterprise Volume Man

agement System (EVMS) Command Line Interpreter (CLI). These com

mand 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 com

mand line used to invoke it. The parameter options on the com

mand 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, seri

ous, 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, en

ter 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 clus

ter.

-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 ex

ecuted.

-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 com

mitted 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 com

mand line arguments are replacement parameters. Replacement pa

rameters 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 ac

cept 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, de

limiters, and values.

ACTIVATE

The Activate command is used to activate volumes or stor

age objects that are not active. If any of the storage objects

that the specified volume or storage object comprises are not ac

tive, 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, acti

vate the volume.

act:/dev/evms/mydata

ADD FEATURE

The Add Feature command adds an EVMS feature to an exist

ing EVMS native volume. The feature is added to the volume by

shrinking the filesystem on the volume to make room for the meta

data of the new feature. The metadata are then written on the

volume. In order to successfully write the metadata for the fea

ture on the volume, EVMS must have a Filesystem Interface Module

(FSIM) for the filesystem on the volume, and the FSIM must sup

port 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 vol

ume.

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 seg

ment 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 seg

ments 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 parti

tioning. Two new storage objects will result from the Assign

command: a metadata segment object and a freespace segment ob

ject. The freespace segment, sdb_freespace1, is created to rep

resent the space available on sdb. This space can be divided in

to 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 Sys

tem Interface Module (FSIM) for the filesystem found on the spec

ified volume.

value is an acceptable value for option name.

COMMIT

The Commit command can be used when the EVMS CLI is run

ning 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 alter

nate 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 significant

ly 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 alter

nate 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 memo

ry 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 Inter

preter to commit to disk all the changes it is currently holding

in memory.

commit

CONVERT

The Convert command has two forms. The first form con

verts 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 compat

ibility 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 sup

port 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 convert

ing 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 con

verted 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 vol

ume. Currently, this conversion can only occur for EVMS volumes

that have no features applied to them.

The Convert command has the following syntax when attempt

ing 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 compat

ibility volume is the type of the resulting volume.

Compatibility

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 ob

jects, regions, segments, and volumes. The different items the

Create

ter 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 cre

ation 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 ob

ject 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_Snap

shot_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 seg

ment 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 deac

tivated, 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 ob

ject, 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

command file.
The Echo command has the following syntax:

Echo : String

where

String is any sequence of ASCII characters except quota

tion 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 vol

ume, 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 contain

ers. 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 re

gions 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 in

crease 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 us

ing 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 seg

ments used to create this EVMS object may be capable of being ex

panded, EVMS Drive Linking allows only the last segment to be ex

panded.

To find the expansion points for a storage object or vol

ume, use the Query Expand Points command. Once you know the ex

pansion 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

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/Sam

ple_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

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 vol

ume 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 com

mands. 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 rec

ognized 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 vol

ume.

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 ob

jects, 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 con

tainer, 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 ob

ject.

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 con

tainer, EVMS object, region, segment, or disk.

Shrink reduces the size of volumes, containers, EVMS ob

jects, 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 rec

ognized 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, re

gions, 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 change

able 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, seg

ments, 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 mod

ules 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 ob

jects, 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 da

ta being returned. A filter restricts what is returned based up

on some characteristic of the items being returned. The avail

able filters for a query depend upon data-type.

When processing a query like the one above, the CLI gath

ers 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 fil

ters 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 Re

turn 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 associa

tion 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 speci

fied 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 mod

ule.

Volume Filter

The Volume filter is available when data-type is

either plug-ins, objects, regions, segments, or disks. This fil

ter 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 us

ing 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 mod

ules 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 cre

ation 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 dis

covered.

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 con

structed without using a region from the specified container.

· For objects, the filter removes any object con

structed 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 re

moves from the Return Values List when data-type is one of the

following:

· For volumes, this filter removes any volume con

structed without using the specified region.

· For objects, this filter removes any object con

structed 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 dis

covered.

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 parti

tioning 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 actu

ally 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 seg

ments 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, re

gion, 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 ob

ject, 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 mod

ule, 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 numer

ic 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 cre

ating 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, seg

ments, or disks that you have decided to use. The query will re

turn any EVMS objects, regions, segments, or disks that are still

available and acceptable for use in creating the container/ob

ject/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 avail

able, use this query again and specify the segments that have al

ready 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 ob

jects, 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, seg

ments, 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 sup

ported 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 expand

ing 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 metada

ta 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 re

vert.

Example:
In this example, assume that you have just created a stor

age 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 alter

nate 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 significant

ly 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 alter

nate 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 In

terpreter'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 Inter

preter 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 manag

er that created that segment can decrease the size of that seg

ment.

You can shrink a more complicated volume in several ways.

For example, you can shrink a volume created from several seg

ments 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 vol

ume 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 seg

ment 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 seg

ments.

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

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/Sam

ple_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, re

gion, 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 over

writing 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 over

writing 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)