HP PolyServe Matrix Server Command Reference Guide

PolyServe Matrix Server

Command Reference

PolyServe Matrix Server 3.1 for Linux

June 2006

Use, reproduction and distribution of this document and the software it describes are subject to the terms of the software license agreement distributed with the product (“License Agreement”). Any use, reproduction, or distribution of this document or the described software not explicitly permitted pursuant to the License Agreement is strictly prohibited unless prior written permission from PolyServe has been received. Information in this document is not guaranteed to be accurate, is subject to change without notice, and does not represent a commitment on the part of PolyServe.

The software this document describes is PolyServe confidential and proprietary.

PolyServe Matrix Server contains software covered by the following copyrights and subject to the licenses included in the file thirdpartylicense.pdf, which is included in the PolyServe Matrix Server distribution.

PolyServe and the PolyServe logo are trademarks of PolyServe, Inc.

All other company, brand, and product names are trademarks or registered trademarks of their respective companies and are hereby recognized.

Contents

1 Matrix Server Commands

destroypsfs – destroy a PSFS filesystem . . . . . . . . . . . . . . . . . . . . . . . . 1

diskupdate – reattempt to access a disk . . . . . . . . . . . . . . . . . . . . . . . . 2

dlmdebug – debug DLM problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

edquota – edit user and group quotas . . . . . . . . . . . . . . . . . . . . . . . . . . 2

emulex/dfc, emulex/lpedit – Emulex utilities . . . . . . . . . . . . . . . . . . . . 2

fsprobe – report filesystem information . . . . . . . . . . . . . . . . . . . . . . . . 3

gcstat – print grpcommd statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

get_fenceidentity – get fencing information . . . . . . . . . . . . . . . . . . . . . 3

hbaapidump – show LUN information . . . . . . . . . . . . . . . . . . . . . . . . . 3

lcl-dump – show information about LCL locks . . . . . . . . . . . . . . . . . . 4

log_collect – obtain log files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

mkpsfs – create a PSFS filesystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

mpdump – Save membership partition data. . . . . . . . . . . . . . . . . . . . 6

mpimport – Restore membership partition data . . . . . . . . . . . . . . . . . 6

mx – Matrix Server command-line interface. . . . . . . . . . . . . . . . . . . . . 8

mxcheck – verify Matrix Server requirements . . . . . . . . . . . . . . . . . . . 8

mxcollect – collect configuration information . . . . . . . . . . . . . . . . . . 10

mxconfig – configure the matrix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

mxconsole – start the Management Console. . . . . . . . . . . . . . . . . . . . 11

mxfence – verify fencing module configuration. . . . . . . . . . . . . . . . . 11

mxfencecfg – configure the fence agent. . . . . . . . . . . . . . . . . . . . . . . . 12

mxinit – manage Matrix Server processes. . . . . . . . . . . . . . . . . . . . . . 13

mxlogger – add a log message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

mxmpconf – manage membership partitions. . . . . . . . . . . . . . . . . . . 17

Setup Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Repair Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Membership Partition Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Repair Menu Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

mxmpio – monitor or manage MPIO devices. . . . . . . . . . . . . . . . . . . 20

Contents iv

Enable or Disable Failover for a Server . . . . . . . . . . . . . . . . . . . . . 21

Enable or Disable Failover for a PSD Device . . . . . . . . . . . . . . . . 22

An Example of Changing the I/O Path. . . . . . . . . . . . . . . . . . . . . . 23

Display Status Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Set the Timeout Value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Show Number of Transient Errors . . . . . . . . . . . . . . . . . . . . . . . . . 24

Show Load Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Display General I/O Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Dump I/O Statistics in Raw Format . . . . . . . . . . . . . . . . . . . . . . . . 25

mxnlmconfig – enable or disable NLM . . . . . . . . . . . . . . . . . . . . . . . . 27

mxpasswd – add users or change passwords. . . . . . . . . . . . . . . . . . . 28

mxperftool – view performance counters . . . . . . . . . . . . . . . . . . . . . . 28

mxsancheck – check server’s SAN access . . . . . . . . . . . . . . . . . . . . . . 29

mxsanconf – configure FC switches . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

mxsanlk – show SAN ownership locks . . . . . . . . . . . . . . . . . . . . . . . . 29

mxsetfence – configure fencing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

mxsetsecret – set the network secret password . . . . . . . . . . . . . . . . . 33

pmxs – start or stop Matrix Server or view status . . . . . . . . . . . . . . . 33

PSANcfg – manage ports, community string . . . . . . . . . . . . . . . . . . . 34

PSANinfo – show FC logins, Naming Database . . . . . . . . . . . . . . . . 34

psdctl – manage device bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

psfsck – check and repair a PSFS filesystem . . . . . . . . . . . . . . . . . . . . 35

psfsdebug – get PSFS filesystem image . . . . . . . . . . . . . . . . . . . . . . . . 38

psfsdq – save quota data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

psfsinfo – report filesystem information . . . . . . . . . . . . . . . . . . . . . . . 39

psfslabel – label a PSFS filesystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

psfsquota – manage disk quotas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

psfsresume – resume a suspended PSFS filesystem . . . . . . . . . . . . . 42

psfsrq – restore quota data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

psfssema – manage matrix-wide file locks . . . . . . . . . . . . . . . . . . . . . 43

psfssuspend – suspend a PSFS filesystem. . . . . . . . . . . . . . . . . . . . . . 44

psfsunpack – unpack a PSFS filesystem image. . . . . . . . . . . . . . . . . . 45

psvctl – manage dynamic volumes . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

quota – report quota information for a user. . . . . . . . . . . . . . . . . . . . 46

repquota – report quota information for a filesystem . . . . . . . . . . . 46

resizepsfs – resize a PSFS filesystem . . . . . . . . . . . . . . . . . . . . . . . . . . 46

sandiskinfo – show SAN disk information . . . . . . . . . . . . . . . . . . . . . 48

Disk Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Options for Dynamic Volumes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

setquota – set quotas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Contents v

snapctl – manage snapshot operations . . . . . . . . . . . . . . . . . . . . . . . . 51

spctl – dump the SanPulse trace buffer . . . . . . . . . . . . . . . . . . . . . . . . 51

spdebug – obtain SanPulse debug information . . . . . . . . . . . . . . . . . 52

spstat – show matrix state information . . . . . . . . . . . . . . . . . . . . . . . . 52

warnquota – warn users of quota limits . . . . . . . . . . . . . . . . . . . . . . . 52

wmtest – test server-based fencing. . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

2 mx Commands

Using the mx utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

The matrixrc file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

mx syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Class syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

mx application – manage applications. . . . . . . . . . . . . . . . . . . . . . . . . 59

mx device – device monitor commands . . . . . . . . . . . . . . . . . . . . . . . 59

mx disk – disk commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

mx dynvolume – dynamic volume commands . . . . . . . . . . . . . . . . . 64

mx exportgroup – Export Group commands . . . . . . . . . . . . . . . . . . . 65

mx fs – filesystem commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

mx matrix – matrix commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

mx netif – network interface commands . . . . . . . . . . . . . . . . . . . . . . . 72

mx notifier – notifier commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

mx quota – filesystem quota commands . . . . . . . . . . . . . . . . . . . . . . . 74

mx server – server commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

mx service – service monitor commands. . . . . . . . . . . . . . . . . . . . . . . 80

mx snapshot – snapshot commands. . . . . . . . . . . . . . . . . . . . . . . . . . . 83

mx vhost – virtual host commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

mx vnfs – Virtual NFS Service commands . . . . . . . . . . . . . . . . . . . . . 85

sleep command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Index

Matrix Server Commands

Matrix Server includes several commands that can be helpful for administrators managing a Matrix Server cluster. Other Matrix Server commands provide diagnostic information and should be used only under the direction of PolyServe personnel. Matrix Server also includes commands that are used internally and should not be run directly.

The Matrix Server commands are located in the following directories:

• /opt/polyserve/bin

• /opt/polyserve/sbin

• /opt/polyserve/tools

• /etc/init.d

destroypsfs – destroy a PSFS filesystem

Synopsis

/opt/polyserve/sbin/destroypsfs

Description

This command removes the specified PSFS filesystem from the volume on which it is located.

Chapter 1: Matrix Server Commands 2

diskupdate – reattempt to access a disk

Synopsis

/opt/polyserve/tools/diskupdate

Description

This command should be run only at the request of PolyServe personnel.

dlmdebug – debug DLM problems

Synopsis/

/opt/polyserve/tools/dlmdebug

Description

This utility should be run only at the request of PolyServe personnel.

edquota – edit user and group quotas

Synopsis/

/opt/polyserve/sbin/edquota

Description

This command is based on the Linux edquota command but has been modified to work with PSFS filesystems as well as the standard Linux filesystem types. The command is provided on the Matrix Server quota tools RPM. There are no changes to the syntax or operation of the command. See the Linux edquota man page for details about the command syntax.

emulex/dfc, emulex/lpedit – Emulex utilities

Synopsis

/opt/polyserve/tools/emulex/dfc /opt/polyserve/tools/emulex/lpedit

Description

These Emulex utilities can be used to view information about Emulex HBAs and to perform tasks such as upgrading firmware. See your Emulex documentation for more information.

Chapter 1: Matrix Server Commands 3

fsprobe – report filesystem information

Synopsis

/opt/polyserve/tools/fsprobe

Description

This command should be run only at the request of PolyServe personnel.

gcstat – print grpcommd statistics

Synopsis

/opt/polyserve/tools/gcstat

Description

This command should be run only at the request of PolyServe personnel.

get_fenceidentity – get fencing information

Synopsis

/opt/polyserve/sbin/get_fenceidentity

Description

The get_fenceidentity utility retrieves the fence identification information for the system on which it is run. The utility is used internally during Matrix Server configuration and should not be run manually.

hbaapidump – show LUN information

Synopsis

/opt/polyserve/tools/hbaapidump

Description

This tool displays information about the LUNs seen by the HBA drivers and can be used to verify that the HBA libraries are working correctly.

Chapter 1: Matrix Server Commands 4

lcl-dump – show information about LCL locks

Synopsis

/opt/polyserve/tools/lcl-dump

Description

This command should be run only at the request of PolyServe personnel.

log_collect – obtain log files

Synopsis

/opt/polyserve/tools/log_collect

Description

This command is used internally by the mxcollect utility and should not be run directly.

mkpsfs – create a PSFS filesystem

Synopsis

/opt/polyserve/sbin/mkpsfs [-n <max-nodes>] [-l <label>] [-o

[

enable-quotas,[userdefault=<size>],[groupdefault=<size>]]

[disable-fzbm]

] <device> [<size-in-blocks>]

Description

The mkpsfs command creates a PSFS filesystem on the specified device, which must be imported into the matrix. PSFS filesystems use a block size of 4 KB.

device is a psd or psv device and is specified as follows:

• For a psd device partition, the device is specified as

/dev/psd/psdXXXpYY, where XXX is the drive number and YY is the partition number. For example, /dev/psd/psd6p4 specifies partition 4 on disk psd6.

• For a non-partitioned psd device, the device is specified as

/dev/psd/psdXXX, where XXX is the drive number. For example, /dev/psd/psd5.

Chapter 1: Matrix Server Commands 5

• For a psv device, the device is specified as /dev/psv/psvXXX, where XXX is the volume number. For example, /dev/psv/psv1.

You do not need to specify the full path name. A name such as psd6p4 or

psv1 will work.

mkpsfs requires exclusive access to the device. If it cannot obtain exclusive

access, it will exit with an “ebusy” message.

The arguments are as follows:

size-in-blocks

The number of blocks on the device. If this value is omitted, mkpsfs will determine it automatically.

-n max-nodes

The maximum number of nodes that can be in the cluster.

-l label

The label to be applied to the filesystem.

The -o option has the following parameters:

disable-fzbm

Create the filesystem without Full Zone Bit Maps (FZBMs). The FZBM on-disk filesystem format reduces the amount of data that the filesystem needs to read when allocating a block. It is particularly useful for speeding up allocation times on large, relatively full filesystems.

enable-quotas

Enables quotas on the filesystem.

userdefault=<size> groupdefault=<size>

Set the default quota limit for users or groups, respectively, to size bytes. (The defaults are rounded down to the nearest filesystem block.) The <size> argument can include one of the following optional modifiers to specify the unit: K (kilobytes), M (megabytes), G (gigabytes), or T (terabytes). If one of these modifiers is not specified, the <size> will be interpreted in bytes. If the default quota limit is not specified on the command line, the limit will be set to 0, which means there is no default limit.

The userdefault and groupdefault parameters are invalid if the enable-quotas parameter is not also specified.

Chapter 1: Matrix Server Commands 6

The following command shows the syntax for the quotas parameters:

mkpsfs -o enable-quotas,userdefault=#[T|G|M|K],groupdefault=#[T|G|M|K] dev

If no -o options are specified, the filesystem will be created with Full Zone Bit Maps (FZBM) and without quotas.

mpdump – Save membership partition data

Synopsis

/opt/polyserve/lib/mpdump

mpdump [-v] -F mpdump [-v] -f <outputfile>

Description

The mpdump utility backs up the membership partition data to a file and/or the screen. When the utility is invoked with no options, the data is output to the screen.

The options are:

-F

Send the data to the default membership partition backup file, /var/opt/polyserve/run/MP.backup. This file can subsequently be used as input to the mpimport utility if needed. If there is an existing backup file, it will be saved as /var/opt/polyserve/run/MP.backup.prev.

-f <outputfile>

Send the data to the specified output file.

-V

Output the data to both the screen and the file.

mpimport – Restore membership partition data

Synopsis

/opt/polyserve/lib/mpimport <options>

Description

The mpimport utility can be used to import disks or dynamic volumes into an existing SCL database. (Either -F or -f is required to import a dynamic

Chapter 1: Matrix Server Commands 7

volume.) The utility can also be used to deport disks or dynamic volumes from the SCL database or to replace a specific UID with a different UID.

NOTE: Matrix Server must be stopped on all nodes when mpimport is used.

Database corruption can occur if the utility is executed while Matrix Server is running on a node. mpimport fails if Matrix Server is running on the current node; however, it does not check the other nodes.

mpimport does not check for the physical presence of the disks or subdevices that it is importing and, for example, allows the devices to be imported even if they are not physically visible on the server. Consequently, successfully completion of the utility does not mean that the imported disks are valid.

The options are:

mpimport <uid> [<uid> ...]

Import the set of disks corresponding to the specified UIDs.

mpimport --local <devname> [<devname> ...]

Import the set of disks corresponding to the specified local disknames.

mpimport -p <psdname> <uid>

Import the disk indicated by the UID and assign the specified psdname to it.

mpimport -p <psdname> --local <devname>

Import the disk indicated by the specified local diskname and assign psdname to it.

mpimport [-s] [-M] -F [<psdname>|<psvname>...]

Import the specified psd or psv devices. If no devices are specified, import all disks and dynamic volumes listed in the default mpdump backup file. If -s is specified, “strict” importing is done; only those disks and dynamic volumes that can be imported using the psdname indicated in inputfile will be imported. If -s is not specified, disks and dynamic volumes will be imported with alternate names if necessary. The -M option recreates the membership partitions from scratch based on the contents of the backup file.

Chapter 1: Matrix Server Commands 8

mpimport [-s] [-M] -f <inputfile> [<psdname>|<psvname>...]

Import the specified psd or psv devices. If no devices are specified, import the disks and dynamic volumes listed in inputfile. The inputfile must be in the format generated by mpdump. If -s is specified, “strict” importing is done; only those disks and dynamic volumes that can be imported using the psdname indicated in inputfile will be imported. If -s is not specified, disks and dynamic volumes will be imported with alternate names if necessary. The -M option recreates the membership partitions from scratch based on the contents of the input file.

mpimport -r <psdname>|<psvname> [<psdname>|<psvname> ...]

Remove the specified disks or dynamic volumes from the existing database.

mpimport --replace <olduid> <newuid>

Replace all occurrences of olduid with newuid throughout the membership partition data.

mx – Matrix Server command-line interface

The mx utility provides a command-line interface for administering a matrix and monitoring its operation. See Chapter 2 for more information about the commands provided with this utility.

mxcheck – verify Matrix Server requirements

Synopsis

/opt/polyserve/bin/mxcheck [-t <text-file>] [-h <html-file>] [-l] [-i] [-r] [-p] [-q] [<sequence>]

Description

The mxcheck utility verifies that a server meets the configuration requirements for Matrix Server. It is run automatically each time Matrix Server is started. Output from the utility appears on the screen and is also written to the /var/opt/polyserve/mxcheck directory. If you are experiencing errors, check the messages in this directory.

The mxcheck utility performs checks such as the following: operating system version and configuration; available physical memory and disk space; HBA driver versions; FibreChannel switch versions; network addresses. The utility also attempts to access gateways and FC switches.

Chapter 1: Matrix Server Commands 9

The logged mxcheck results can be seen remotely with a web browser, via https://<hostname>:9071/mxcheck/. For example:

https://sysa.yourcompany.com:9071/mxcheck/

You will need to know the username and password for a Matrix Server user account such as admin.

The options are:

-t <text-file> and/or -h <html-file>

Place the output in a text or html file. A

- implies standard out.

-l

Log output to /var/opt/polyserve/mxcheck. (Does indexing and suppresses the default text report.)

-i

Regenerate index.html in /var/opt/polyserve/mxcheck. (Suppresses default sequence execution and report.)

-r

Remove all but the last 40 logged reports. (Does indexing, suppresses default text report. Without -l, suppresses default sequence.)

-p

Prompt for user input when necessary. Also disables timeouts for individual tests.

-q

Suppress progress messages.

The available sequences are as follows:

• install. Intended to be invoked manually during Matrix Server

installation.

• prestart. The default sequence when a server is rebooted.

In general, we recommend that you run mxcheck with no options.

Chapter 1: Matrix Server Commands 10

mxcollect – collect configuration information

Synopsis

/opt/polyserve/tools/mxcollect

Description

This script collects configuration information and log files from the matrix. The script is typically run under the direction of PolyServe Technical Support.

mxconfig – configure the matrix

Synopsis

/opt/polyserve/bin/mxconfig [--import] [--help]

Description

The mxconfig utility performs the initial configuration of Matrix Server. mxconfig invokes a dialog-based interface that allows you to install the

Matrix Server license file, to select a matrix password and a Network Authentication Secret password, to select a fencing method and optionally configure the FibreChannel switches to be used in the matrix, and to select the SAN disk partitions to be used as Matrix Server membership partitions.

You can ru n mxconfig on one server and then export the resulting configuration to the other servers. You must be root to run this utility.

The options are:

--help

Display a usage message.

--import

Import a Matrix Server configuration from an existing matrix server to a new server.

See the PolyServe Matrix Server Installation Guide for more information about mxconfig.

Chapter 1: Matrix Server Commands 11

mxconsole – start the Management Console

Synopsis

/opt/polyserve/bin/mxconsole [--matrix <matrix>] [--config <file>] [--user <username>]

Description

The mxconsole command starts the Management Console, which is used to configure and monitor the matrix. The Management Console can be run from either a matrix server or a local machine outside the matrix. (See the PolyServe Matrix Server Administration Guide for information about using the Management Console.)

To use the options, a matrixrc file must exist on the server. This file contains the user names and passwords that Matrix Server uses for authentication. For more information, see “The matrixrc file” on page 54.

The options are:

--matrix <matrix>

Specifies the matrix that you want to connect with. matrix can be any node in the matrix.

--config <file>

Specifies the configuration file to be consulted for server, user, and password information. The file must have the same format as matrixrc.

--user <username>

Specifies the user to be logged in.

mxfence – verify fencing module configuration

Synopsis

/opt/polyserve/sbin/mxfence <server hostname or IP address>

Description

The mxfence utility can be used to verify that Matrix Server has the information needed to fence a server. This utility is intended for server-based fencing configurations where you must specify the hostname or IP address of the remote controller associated with the server. You can use mxfence to

Chapter 1: Matrix Server Commands 12

verify that Matrix Server has the correct information. The server must be up when you use the utility and Matrix Server must be stopped on that server.

When you run mxfence, Matrix Server uses the hostname/IP address associated with the server to access the remote controller. The server is then either power-cycled or shut down in accordance with the method you selected when you configured the fencing module.

If the correct server is not fenced, the hostname or IP address specified for the associated remote controller is probably incorrect. Run mxconfig on the server with the incorrect information and then modify the hostname or IP address for the remote controller.

mxfencecfg – configure the fence agent

Synopsis

/opt/polyserve/bin/mxfencecfg mxfencecfg -r|-s -v <vendor> [-b <blade number>]

-i <IP address of remote controller>

-u <username> -p <password>

Description

The mxfencecfg command is used in conjunction with mxsetfence to configure flexible fencing without running mxconfig. The mxsetfence command is run first, as described under “mxsetfence – configure fencing” on page 32.

If you are using the fcsan fence agent, run the mxfencecfg command with no parameters, as no additional configuration is needed.

For the webmgt fence agent, specify the appropriate fence parameters:

-r

Set the fencing action to

RESET.

-s

Set the fencing action to

SHUTDOWN.

-v <vendor> Specify the vendor for the remote controller (dell, hp, or ibm).

-b <blade number>

For a blade server, specify the blade number.

Chapter 1: Matrix Server Commands 13

-i <IP address of remote controller>

Specify the IP address of the remote controller.

-u <username>

Specify the username needed to access the remote controller.

-p <password>

Specify the password needed to access the remote controller.

mxinit – manage Matrix Server processes

Synopsis

/opt/polyserve/bin/mxinit [-s, --start] [-x, --stop] [-H, --hard] [-g, --status] [-L, --load-mod] [-U, --unload-mod] [-f file, --alt-config-file file] [-m, --monitor] [-M, --no-monitor] [--hba-status] [--status] [--version] [-v, --verbose] [-h, -?, --help]

Description

The mxinit utility is started automatically as a daemon on each server and monitors all Matrix Server processes running there. (You can start another instance of mxinit to perform other tasks provided by the utility.)

If a Matrix Server process dies unexpectedly on a server, mxinit will restart it if possible. However, certain process failures may force a restart of that particular server.

When you invoke mxinit to start Matrix Server, by default it continues running and monitors processes. If you do not want mxinit to monitor processes, invoke it with the -M (or --no-monitor) option. It will then exit after it completes the options you specified.

Chapter 1: Matrix Server Commands 14

Typically, you should use the pmxs script to start or stop Matrix Server. However, if you want to see verbose output during the start or stop operation, you can run mxinit manually with the --verbose option.

mxinit performs its actions according to a set of default values. You can use the /etc/opt/polyserve/mxinit.conf configuration file to override the default values. The file describes the available options and the required format. We recommend that you change this file only at the request of PolyServe personnel.

The mxinit options are:

-s, --start Start the Matrix Server processes.

-x, --stop Gently stop the Matrix Server processes. mxinit first attempts to unmount PSFS filesystems. If the unmount fails, the gentle stop operation will also fail.

If you specify both --stop and --hard, the mxinit command first attempts the --stop operation. If it fails, mxinit then executes the --hard operation.

-H, --hard Perform a hard, immediate stop of the Matrix Server processes. mxinit first attempts to terminate any applications accessing PSFS filesystems. It then unmounts the filesystems, terminates the Matrix Server processes, and unloads Matrix Server modules.

-L, --load-mod Load all Matrix Server modules.

-U, --unload-mod Unload all Matrix Server modules.

-f file, --alt-config-file file Use the specified configuration file instead of the default configuration file

(/etc/opt/polyserve/mxinit.conf).

-v, --verbose Print verbose output about each step of the mxinit operation.

Chapter 1: Matrix Server Commands 15

--version

Display the version of Matrix Server.

-m, --monitor Explicitly tell mxinit to monitor processes. This is the default when mxinit is invoked to start Matrix Server.

-M, --no-monitor Explicitly tell mxinit not to monitor processes.

--hba-status

Display the state of the FibreChannel host bus adapter drivers.

--status

Display the status of Matrix Server processes and modules. Following is an example.

$ status PolyServe Matrix Server Status: Name pid / status mxinit 15930 mxinit: Monitoring MxS processes mxlog Loaded grpcommd 15885 mxlogd 15887 pswebsvr 15890 clusterpulse 15892 panpulse 15912 psd_devfs Loaded psfs Loaded dlm 15913 sanpulse 15917

FibreChannel adapter module status: qla2300 - QLogic 2300 FibreChannel Adapter, is Loaded

The PID is displayed for running processes; “Stopped” is displayed for processes that are not running. For modules, the status specifies whether the module is loaded. The “FibreChannel adapter module status” section displays status for the FibreChannel adapter modules installed on the system.

Chapter 1: Matrix Server Commands 16

mxlogger – add a log message

Synopsis

/opt/polyserve/bin/mxlogger -e <entity> -l <level> [-G|-L] <log-text>

/opt/polyserve/bin/mxlogger [-h]

Description

You can use the mxlogger command to add your own messages to the matrix.log file. For example, you may want to add messages about the state of your applications.

The arguments are:

-h

Print a help message.

-e entity

The type of message that you are adding. entity can be

USER3, USER4, USER5, USER6, USER7, or USER8

. You will need to determine

how you want to use these entities.

-l level The severity of the message. level can be

FATAL, STATE, TRACE, or DEBUG

ERROR, WARN, INFO, EVENT,

-G|L

-G specifies that the message to be added is global; -L specifies that it is

local. The default is local.

log-text

The text of the message. If log-text contains special characters or spaces, it must be enclosed in quotation marks.

The following command adds a local message to the matrix.log file:

USER1, USER2,

mxlogger -l info -e User2 “hello, world.”

The message appears like this in the log file:

Server Level Date/time Facility Entity Message

192.168.0.1 [Info] [2001-10-07 14:16:27] User USER2 hello, world

Chapter 1: Matrix Server Commands 17

mxmpconf – manage membership partitions

Synopsis

/opt/polyserve/bin/mxmpconf

NOTE: Matrix Server cannot be running when you use mxmpconf. To stop

the matrix, use the following command:

# /etc/init.d/pmxs stop

Description

The mxmpconf utility starts an ASCII interface that can be used to create a new set of membership partitions or to repair the existing partitions

Membership partitions control access to the SAN and store the device naming database, which includes the global device names for SAN disks imported into the matrix. Each server in the matrix has a membership partition file, which is called the “local MP list.” This file specifies the locations of the membership partitions. Each membership partition also has its own MP list. Because the membership partitions control access to the SAN, it is important that all servers in the matrix have the same view of where the partitions are located. The mxmpconf utility can be used to repair any problems if a failure causes servers to have inconsistent views of the membership partitions.

For detailed information about mxmpconf, see the PolyServe Matrix Server Administration Guide.

Setup Option

The Setup option allows you to create a new set of membership partitions. You can select up to three SAN partitions to be used as membership partitions. It is recommended that the partitions be on separate disks.

Repair Menu

The Repair Menu lists the current membership partitions according to the MP file maintained on the server where you are running the utility.

Membership partitions are either active or inactive. The current membership partitions are active. There can also be old membership partitions in the matrix that are now inactive.

Chapter 1: Matrix Server Commands 18

Membership Partition Status

The Repair Menu reports the status of each membership partition. The status will be one of the following:

OK. The membership partition is included in the local membership partition list. This is the normal status.

NOT FOUND. The mxmpconf utility cannot find the device containing the membership partition.

INACCESSIBLE. The mxmpconf utility cannot access the device containing the membership partition.

CORRUPT. The partition is not valid.

MISMATCH. The membership partition is valid but its MP list does not

match the server’s local MP list.

If the status is

NOT FOUND or INACCESSIBLE, there may be a problem with

the disk or with another SAN component. When the problem is repaired, the status should return to

If the status is

CORRUPT, you should resilver the partition. This step copies

OK.

the membership data from a valid membership partition to the corrupted partition.

NOTE: The membership partition may have become corrupt because it was

used by another application. Before resilvering, verify that it is okay to overwrite any existing data on the partition.

If the status is

MISMATCH, you will need to determine which membership

partitions are correct (either the partitions specified in the local MP list, or the partition labeled

MISMATCH) and resilver accordingly.

Repair Menu Options

The Repair Menu includes the following options:

Resilver

Asks you to select a membership partition and then copies the data from that partition to the other membership partitions.

Chapter 1: Matrix Server Commands 19

NOTE: If you resilver from a partition that is labeled MISMATCH, the

operation may initialize partitions that are not currently membership partitions; any existing data on those partitions will be overwritten. Use the Display option to see the membership partition lists for the current membership partitions.

Add

Allows you to select a new membership partition. This operation configures the new partition as a membership partition, copies the data on the existing membership partitions to the new partition, and updates the local MP list and the lists on the existing membership partitions. This option appears only if there are fewer than three membership partitions. All membership partitions must have a status of OK.

Remove

Allows you to remove an existing membership partition. This operation removes the membership data and formatting from the partition. It also deletes the partition from the local MP list and from the membership partition lists on the remaining membership partitions.

Replace

Allows you to remove an existing membership partition and then to select a partition to replace it. (When you have completed your selections, choose “Done”.) All membership partitions must currently have a status of OK.

Display

Shows the local membership partition list on the server where you are running mxmpconf and also displays the lists located on the disks containing the membership partitions. The output also includes the device database records for the disks containing the membership partitions.

Searches the SAN for all partitions that appear to be membership partitions. The output includes each membership partition found by the search and specifies whether the partition is active or inactive. The output also displays the membership lists from the membership partitions and the database records for the partitions.

Inactivate

Inactivates membership partitions that are marked as active but are not part of the current set defined by the membership partition list. This

Chapter 1: Matrix Server Commands 20

option is useful if the matrix includes old membership partitions that are marked active or if you want to import a disk that contains an active membership partition.

Clear the Host Registry

This option removes all entries from the server registry.

CAUTION: Before clearing the server registry, be sure to reboot or power

off any servers that were previously removed from the matrix and no longer had access to the SAN. After the servers have been rebooted, they can safely access the SAN. (If the servers are not rebooted, it is possible for them to corrupt filesystems.)

mxmpio – monitor or manage MPIO devices

Synopsis

/opt/polyserve/bin/mxmpio command [options...] [parameters ...] [PSD-devices ...]

Description

Matrix Server uses multipath I/O (MPIO) to eliminate single points of failure. A matrix can include multiple FibreChannel switches, multiple FC ports per server, and multiported SAN disks. This configuration provides multiple paths for I/O between matrix servers and SAN disks.

When you start Matrix Server, it automatically configures all paths from each matrix server to the storage devices. On each server, it uses the first path it discovered for I/O with the SAN devices. If that path fails, Matrix Server automatically fails over the I/O to another path.

The mxmpio command can be used to display status information about MPIO devices or to control the path used for I/O. With the exception of enableall and disableall, all commands take PSD device names to operate on specific devices. If you do not specify a PSD device, the command operates on all devices.

The options are:

-l

Long option. Provides more detail about targets. This option does not apply to enableall or disableall.

Chapter 1: Matrix Server Commands 21

-u

Display I/O latencies in microseconds instead of the default milliseconds. This option applies only to the iostat command.

The commands are:

enable/disable

Enable or disable MPIO failover on the specified devices.

enableall/disableall

Globally enable or disable MPIO failover on this node.

timeout value

Set the timeout on the specified device.

active target

Set the active target on the specified device.

mpiostat

List the number of transient errors for each target and show the number of failovers and fatal errors for each device.

mpioload [interval [count]]

Shows the load for each target (SCSI command I/Os) and total for the PSD device (block layer I/Os), number of failovers, and fatal errors for each device.

iostat [interval [count]]

Show general I/O statistics for each device.

iostat [interval [count]]

Dump general I/O statistics for each device in a raw format.

Enable or Disable Failover for a Server

A matrix server can use multiple FC ports to connect to the FibreChannel fabric. If the FC port or FC switch currently being used for I/O should fail, Matrix Server will by default fail over the I/O to another FC port/FC switch path.

You can use the following command to control whether this failover behavior can occur on a particular node. Run the command on the server where you want to change the failover behavior. (Matrix Server starts with failover enabled.)

# mxmpio enableall|disableall

Chapter 1: Matrix Server Commands 22

Enable or Disable Failover for a PSD Device

When a failure occurs in the I/O path to a particular PSD device, Matrix Server will by default fail over to another I/O path. You can use the following command to control whether this failover behavior can occur for specific PSD devices. Matrix Server starts with failover enabled.

# mxmpio enable|disable [<PSD-device ...>]

Specify the Path for I/O

If you are troubleshooting problems with an I/O path, you may want to direct the I/O to another I/O path. You might also want to manually balance I/O paths on a per-server basis across the cluster. This is possible because mxmpioʹs controls are server specific.

You can use the following command to specify either a particular HBA or a PSD device. Matrix Server will then fail over the I/O to the path that includes the specified device. In the command, PSD-device is specified by the base name of the device path, such as psd2p1 (not /dev/psd/psd2p1).

# mxmpio active <target> <PSD-device>

target can be one of the following values:

I A numerical index on the PSD device target array (0..).

M,m A decimal major/minor number identifying the host adapter.

M:m A hexadecimal major/minor number identifying the host

adapter.

scsiN/C A scsi bus ID. N is the scsi host adapter ID (0..) and C is the scsi

host channel number (0..) as defined in /proc/scsi/scsi and /proc/scsi/*/[0-9]. If C is omitted, zero is assumed.

sdNsP A device node in /dev. The value is converted to a major/minor

number identifying the corresponding host adapter.

With the exception of I (the array index), the value specified is converted to the corresponding host adapter/channel before being used to select the target.

Chapter 1: Matrix Server Commands 23

An Example of Changing the I/O Path

In this example, we will change the target for a device. The mxmpio status -l command identifies the path currently being used by each device. That path is labeled “active.” The following output shows that device psd2p1 is active on target 1.

# /opt/polyserve/sbin/mxmpio status -l MPIO Failover is globally enabled Failover Timeout Targets psd1 enabled 30000 0. (41:50) scsi2/0/2/19 (active)

1. (08:90) scsi1/0/2/19

psd1p1 enabled 10000 0. (41:51) scsi2/0/2/19

1. (08:91) scsi1/0/2/19 (active)

psd1p2 enabled 30000 0. (41:52) scsi2/0/2/19 (active)

1. (08:92) scsi1/0/2/19

psd2 enabled 30000 0. (41:10) scsi2/0/1/20 (active)

1. (08:50) scsi1/0/1/20

psd2p1 enabled 10000 0. (41:11) scsi2/0/1/20

1. (08:51) scsi1/0/1/20 (active)

psd2p2 enabled 30000 0. (41:12) scsi2/0/1/20 (active)

1. (08:52) scsi1/0/1/20

Now use the mxmpio command to change the path for psd2p1 to target 0:

# /opt/polyserve/sbin/mxmpio active 0 psd2p1

To verify the change, run the mxmpio status -l command again. In the following output, device psd2p1 is now active on target 0.

# /opt/polyserve/sbin/mxmpio status -l MPIO Failover is globally enabled Failover Timeout Targets psd1 enabled 30000 0. (41:50) scsi2/0/2/19 (active)

1. (08:90) scsi1/0/2/19

psd1p1 enabled 10000 0. (41:51) scsi2/0/2/19

1. (08:91) scsi1/0/2/19 (active)

psd1p2 enabled 30000 0. (41:52) scsi2/0/2/19 (active)

1. (08:92) scsi1/0/2/19

psd2 enabled 30000 0. (41:10) scsi2/0/1/20 (active)

1. (08:50) scsi1/0/1/20

psd2p1 enabled 10000 0. (41:11) scsi2/0/1/20 (active)

1. (08:51) scsi1/0/1/20

psd2p2 enabled 30000 0. (41:12) scsi2/0/1/20 (active)

1. (08:52) scsi1/0/1/20

Chapter 1: Matrix Server Commands 24

Display Status Information

The status command displays MPIO status information, including the timeout value, whether MPIO is enabled (globally and per-device), and any targets specified with the active command. Use the -l option to display more information about the targets, as in the above example.

$ mxmpio status

In contrast with the earlier example, this example shows output for a system that is not MPIO:

# /opt/polyserve/sbin/mxmpio status -l MPIO Failover is globally enabled Failover Timeout Targets psd1 enabled 30000 0. (41:50) scsi2/0/2/19 psd1p1 enabled 10000 0. (41:51) scsi2/0/2/19 psd1p2 enabled 30000 0. (41:52) scsi2/0/2/19 psd2 enabled 30000 0. (41:10) scsi2/0/1/20 psd2p1 enabled 10000 0. (41:11) scsi2/0/1/20 psd2p2 enabled 30000 0. (41:12) scsi2/0/1/20

Set the Timeout Value

The default timeout period for PSD devices is 30 seconds. If you need to modify this value for a particular PSD device, use the following command. value is in milliseconds; however, the smallest unit is 10 milliseconds. A value of zero disables timeouts.

# mxmpio timeout value [PSD-device]

Show Number of Transient Errors

The mpiostat command lists the number of transient errors for each target and shows the number of failovers and fatal errors for each device. Values represent the number of respective events since the device was bound. If devices have not been rebound since boot, then this represents the number of events since boot.

Show Load Statistics

The mpioload command shows the load (number of pending I/Os, both total and raw) for each target (SCSI command I/Os) and total for the PSD device (block layer I/Os), number of failovers, and fatal errors for each device.

+ 66 hidden pages