logo

Manual Pages


Table of Contents

NAME

lun - Commands for managing luns

SYNOPSIS

lun command argument ...

DESCRIPTION

The lun command is used to create and manage luns, and their mappings using SAN protocols.

USAGE

The following commands are available in the lun suite:

  clone          help           online         share
  comment        map            resize         show
  config_check   maxsize        serial         snap
  create         move           set            stats
  destroy        offline        setup          unmap

LUN cloning allows the user to create a copy of a LUN, which was initially created to be backed by a LUN or a file in a snapshot (i.e. using lun clone create ). LUN cloning creates a complete copy of the LUN and frees the snapshot, which can then be deleted. The following commands can be used to manage this feature:

lun clone create clone_lunpath [ -o noreserve ] -b parent_lunpath parent_snap

The lun clone create command creates a lun on the local filer that is a clone of a "backing" lun. A clone is a lun that is a writable snapshot of another lun. Initially, the clone and its parent share the same storage; more storage space is consumed only as one lun or the other changes.

The parent_snap is locked in the parent volume, preventing its deletion until the clone is either destroyed or split from the parent using the lun clone split start command.

The lun clone create command fails if the chosen parent_lunpath is currently involved in a lun clone split operation.

lun clone split start [-d] lun_path

This command begins separating clone lun_path from its underlying parent. New storage is allocated for the clone lun that is distinct from the parent.

This process may take some time and proceeds in the background. Use the lun clone split status command to view the command's progress.

Both clone and parent luns remain available during this process of splitting them apart. Upon completion, the snapshot on which the clone was based will be unlocked in the parent vol.

With the -d option supplied, disables space-efficient splitting in favor of the legacy style of splitting clones.

lun clone split status [ lun_path ]

This command displays the progress in separating clone luns from their underlying parent luns.

lun clone split stop lun_path

This command stops the process of separating a clone from its parent lun. All of the blocks that were formerly shared between lun_path and its backing lun that have already been split apart by the lun clone split start will remain split apart.

lun clone show [ lun_path ]

If no lun_path is given, information about all luns being cloned is shown. Usage of lun clone show has been deprecated. Instead, please use lun clone split status.

Displays the cloning status of the lun in terms of percentage complete.

lun clone start lun_path

Start the cloning of the lun at the given lun_path. Only LUNs backed by a snapshot can be cloned.

Usage of lun clone start has been deprecated. Instead, please use lun clone split start.

lun clone status lun_path

Display the status of the cloning of the lun at the given lun_path. This gives details about number of blocks processed until now.

Usage of lun clone status has been deprecated. Please use lun show -v or lun clone split status to display cloning status.

lun clone stop lun_path

Stop the cloning of the lun at the given lun_path.

Usage of lun clone stop has been deprecated. Instead, please use lun clone split stop.

lun comment lun_path [ comment ]

This command is used to display or change a comment string associated with the lun. If the comment string to be supplied has white space, it should be enclosed in double quotes.

lun config_check [ -S ] [ -s | -v ]

config_check performs several checks on the lun/igroup/fcp configuration of the filer. The -v flag enables verbose output which lists the tests being done. The -s flag runs the command in a silent mode and disable all output unless problems are discovered. The -S flag runs the `SSI' checks when not running in that cfmode. The specific checks are as follows:

Compatibility of initiator group ostype and the fcp cfmode setting

FCP HBAs which are not online

FCP cfmodes are set to the same thing on each filer in the cluster

Initiator names which are members of initiator groups with different ostype settings

The SSI checks test for lun maps that conflict with maps on the partner, and fcp nodenames that are different between the local and partner filer.

lun create -s size -t ostype [ -o noreserve ] [ -e space_alloc ] lun_path

This usage of the lun create command should be employed to create a new lun of given size, with initially zero contents. The lun is created at the lun_path given. No file should already exist at the given lun_path. The directory specified in the lun_path must be a qtree root directory.

The size is specified in bytes. Optionally, a number followed by a one-character multiplier suffix can be used: c (1), w (2), b (512), k (1024), m (k*k), g (k*m), t (m*m).

The size of the created lun could be larger than the size specified, in order to get an integral number of cylinders while reporting the geometry using SAN protocols.

The size of the lun actually created is reported if it is different from that specified in the command.

The mandatory ostype argument is one of: solaris (the lun will be used to store a Solaris raw disk in a single-slice partition), windows (the lun will be used to store a raw disk device in a single-partition Windows disk using the MBR (Master Boot Record) partitioning style), hpux (the lun will be used to store HP-UX data), aix (the lun will be used to store AIX data), vld (the lun contains a SnapManager VLD), linux (the lun will be used to store a Linux raw disk without any partition table), netware (the lun will be used to store NetWare data), vmware (the lun will be used to store VMware data), windows_gpt (the lun will be used to store Windows data using the GPT (GUID Partiton Type) partitioning style), windows_2008 (the lun will be used to store Windows data for Windows 2008 systems), openvms (the lun will be used to store Open-VMS data), xen (the lun will be used to store Xen data), hyper_v (the lun will be used to store Hyper-V data), solaris_efi (the lun will be used to store Solaris_EFI data),

By default, the lun is space-reserved. If it is desired to manage space usage manually instead, -o noreserve can be specified. Using this option will create a LUN without any space being reserved. Provisioning threshold events can be enabled by specifying -e space_alloc option. This option has to be used in conjunction with -o noreserve.

lun create -f file_path -t ostype [ -o noreserve ] [ -e space_alloc ] lun_path

Create a lun from an existing file. A new lun is created, at the given lun_path (which must be at a qtree root). A hard link is created to the existing file. The file contents are not copied or changed. The file can be resized to a larger size, rounding up to a cylinder boundary. If the -o noreserve option is used, make sure that the file does not have any space reservations enabled using the file reservation command. Provisioning threshold events can be enabled by specifying -e space_alloc option. This option has to be used in conjunction with -o noreserve.

lun create -b snapshot_lun_path [ -o noreserve ] lun_path

A lun is created in the active file system. The lun has the same initial contents as the referenced snapshot copy of an existing lun. (Note that no copy of the data is made.)

Any subsequent writes to this new lun would not affect the lun in the snapshot. All reads to the new lun would be served by the latest content of the lun.

Usage of lun create -b has been deprecated. Instead, please use lun clone create.

lun destroy [ -f ] lun_path...

The specified lun(s) are destroyed. The data container, and the configuration information are discarded. This operation will fail if the lun is currently mapped and is online.

The optional -f argument forces the lun(s) to be destroyed regardless of being mapped or online.

lun help [ subcommand ]

With no arguments, available subcommands are listed with brief help texts. When a subcommand name is supplied, more detailed help for the specific subcommand is displayed.

lun map [ -f ] lun_path initiator_group [ lun_id ]

Maps a lun to all the initiators in the supplied group. If a LUN ID is not specified, the smallest number that can be used for the various initiators in the group is automatically picked. Note that this command can be used multiple times to configure multiple maps for a lun, or for an initiator group. Once created you can use lun show -m to list all the LUN mappings.

The optional -f argument disables checking with the cluster partner for lun mapping conflicts.

lun maxsize path

This command returns the maximum possible size of a lun on a given volume or qtree. The user can pass the path to a volume or qtree in which the lun is to be created. The command returns the maximum size for different types of luns and the possible maximum size with snapshots or without snapshots.

lun move lun_path to_lun_path

Moves the lun to a new path in the same volume. Both lun_path and to_lun_path should be in the same volume.

lun offline lun_path...

Disables block-protocol accesses to the lun(s). Mappings, if any, configured for the lun are not altered. Note that unless explicitly offlined, a lun is online.

lun online [ -f ] lun_path...

Re-enables block-protocol accesses to the lun(s). See lun offline for further information.

The optional -f argument disables checking with the cluster partner for lun mapping conflicts.

lun resize [ -f ] lun_path [ + | - ] size

Changes the size of the lun to the input value size. Optional + or - can be used with size to increase or decrease the lun size by the given amount. Although it is possible to resize the LUN without offlining the LUN first, doing so prevents any potential problems on the host side. Note that client-side operations may be needed to ensure that client software recognizes the changed size. The -f flag or manual confirmation is required to reduce the size of a LUN. The LUN may be resized to a larger size than specified, rounding up to a cylinder boundary.

lun serial lun_path [ serial_number ]

Displays the persistent serial number associated with the lun. If a serial number is supplied, it is used for the lun henceforth. The lun must first be made offline using the lun offline command before changing the serial number. The serial number is a 12-character string formed of upper and lower-case letters, numbers, and slash (/) and hyphen (-) characters.

lun set dev_id lun_path { dev_id | none }

Sets the Device Identifier that is returned in response to a REPORT DEVICE IDENTIFIER SCSI command for the specified lun_path. The dev_id value may be 1-9999. To remove the Device ID set the Device ID to none.

lun set reservation lun_path [ enable | disable ]

Enables or disables the space reservation on the LUN. If no arguments are supplied after the lun_path, then the space reservation status of the given lun_path is displayed.

lun set space_alloc lun_path [ enable | disable ]

Enables or disables reporting of provisioning threshold events on the LUN. If no arguments are supplied after the lun_path, then the reporting status of the given lun_path is displayed.

lun set svo_offset lun_path [ offset | disable ]

Set the offset used by SnapValidator for Oracle to calculate block numbers in the presence of a host volume manager on the lun. The offset specifies the number of bytes from the beginning of the lun to the start of Oracle data. Setting the offset to disable will disable SnapValidator checking on this lun. This is the default setting.

lun setup

Easy to use interactive mechanism for setting up initiator groups, LUNs and mapping configuration.

lun share lun_path { all | none | read | write }

Enables file system protocol-based access to a lun. By default, all accesses are disallowed. Note that file permissions and ACL entries still apply.

lun show [ -v | -m | -c ] [ all | mapped | offline | online | unmapped | staging | -g initiator_group | -n node | lun_path ]

Displays the status (lun_path, size, online/offline state, shared state) of the given lun or class of luns. With the -v flag supplied, additional information (comment string, serial number, LUN mapping) is also displayed. With the -m flag supplied, information about lun_path to initiator_group mappings is displayed in a table format. With the -c flag supplied, information about lun cloning status is displayed.

A specific lun can be indicated by supplying its lun_path. When an initiator_group is specified, status is reported for all luns that are mapped to the initiator group. When a node is specified, status is reported for all luns that are mapped to initiator groups which contain that node. When staging is specified, information about the temporary luns preserved in the staging area is reported.

Mapped luns are ones with at least one map definition. A lun is online if it has not been explicitly made offline using the lun offline command.

lun snap usage [ -s ] vol_name snap_name

Displays information about all LUNs in active file system and snapshots that are backed by the given snapshot

This command displays all the LUNs in all the existing snapshots which are currently backed by data in the given snapshot snap_name. If you wish to delete the given snapshot snap_name then you must first destroy all those LUNs in the active file system, which are listed in the output. Thereafter, if vol options snapshot_clone_dependency is not set, you need to delete all the snapshots listed in the output starting from the one listed at the top. Once this is done you can then delete the snapshot snap_name. The -s option provides a summary view of the information.

lun stats [ -o ] [ -a | lun_path ]

Displays or zeroes block-protocol access statistics for luns. The time since the stats were last zeroed is displayed for each lun.

The statistics start zeroed at boot time. Thereafter, the -z option zeroes statistics (but does not display them).

The -o option will display extra statistics.

The -a option will display all LUNs. Normally only LUNs with non-zero statistics are displayed.

With no lun_path specified, statistics for all the LUNs are displayed; alternatively, only for the specified LUN.

The default output format is as follows:

  /vol/volname/lun  (## hours, ## minutes, ## seconds)
      Read (kbytes)   Write (kbytes)  Read Ops  Write Ops
      ######          ######          ######    ######

The -o output format is as follows:

  /vol/volname/lun  (## hours, ## minutes, ## seconds)
      Read (kbytes)   Write (kbytes)  Read Ops  Write Ops  Other Ops  QFulls  Partner Ops Partner KBytes
      ######          ######          ######    ######     ######     ######  #####       ######

lun stats -i interval [ -c count ] [ -o ] [ -a | lun_path ]

The -i option will report per LUN performance statistics at the per second interval given. The -c argument will cause output to stop after the give number of iterations.

The default output format for -i is as follows:

   Read Write   Read  Write Average   Queue  Lun
    Ops   Ops     kB     kB Latency  Length
   ####  ####  #####  #####   ##.##  ###.##  lun_path

The -i -o output format is as follows:

   Read Write Other QFull   Read  Write Average   Queue     Partner  Lun
    Ops   Ops   Ops           kB     kB Latency  Length   Ops     kB
  ##### ##### ##### ##### ###### ######   ##.##  ###.##  ####  ##### lun_path

where

Read Ops The number of SCSI read operations per second.

Write Ops The number of SCSI write operations per second.

Other Ops The number of other SCSI operations per second.

QFull
The number of SCSI Queue Full responses sent per second.

Read kB
Kilobytes per second read traffic.

Write kB Kilobytes per second write traffic.

Average Latency
Average in milliseconds to process a request for the LUN.

Queue Length
The average number of outstanding requests pending.

Partner Ops
The number of SCSI operations received via the Partner path (included in the Read, Write, and Other ops)

Partner kB
Kilobtyes per second of SCSI traffic via the Partner path (included in Read kB and Write kb)

Lun
The path to the LUN.

lun stats -z [ lun_path ]

zeroes the statistics for the given lun_path or all LUNs if no path is specified.

lun unmap lun_path initiator_group

Reverses the effect of a lun map command.

CLUSTER CONSIDERATIONS

While the system is in takeover mode, luns belonging to either host can be managed using the lun command.

VFILER CONSIDERATIONS

When run from a vfiler context (e.g. via the vfiler run command), lun operates on the concerned vfiler. Luns can be created only on storage owned by the vfiler context. The lun command may operate only on luns created by the vfiler context on which the command is executed. Lun maps must refer to initiator groups that have been created within the same vfiler context.

EXAMPLES

lun clone create /vol/vol0/myclone -o noreserve -b /vol/vol0/lun0 nightly.0

Creates the LUN clone named myclone in volume /vol/vol0 from the snapshot backed lun named lun0 also found in /vol/vol0 using the snapshot of /vol/vol0 named nightly.0.

lun resize /vol/vol1/lunY 20g

Resizes the LUN /vol/vol1/lunY to 20G.

lun snap usage vol1 mysnap

Active:
LUN: /vol/vol1/lun01c
Backed By: /vol/vol1/.snapshot/mysnap/lun01

oldsnap:
LUN: /vol/vol1/.snapshot/oldsnap/lun02c Backed By: /vol/vol1/.snapshot/mysnap/lun02

This means that one first needs to destroy LUN /vol/vol1/lun01c before snapshot mysnap can be deleted. If vol option snapshot_clone_dependency is not set then oldsnap will also have to be deleted before snapshot mysnap can be deleted.

SEE ALSO

na_vfiler(1), na_fcp(1), na_igroup(1), na_iscsi(1), na_san(1)


Table of Contents