.\" cvlabel.8: auto-generated, DO NOT EDIT .\" .\" Copyright 1998-2024. Quantum Corporation. All Rights Reserved. .\" StorNext is either a trademark or registered trademark of .\" Quantum Corporation in the US and/or other countries. .\" .\" Code start macro .de Cs .sp .ft C .in +0.3i .nf .. .\" Code end macro .de Ce .fi .in -0.3i .ft R .. .TH CVLABEL 8 "January 2024" "Xsan File System" .SH NAME cvlabel \- Label Xsan Disk Devices (LUNs) .SH SYNOPSIS .na .nh .HP .B cvlabel -l .RB [ \-agsv ] .RB [ \-F \ \fIfilter\fP] .HP .B cvlabel -L .RB [ \-agv ] .RB [ \-F \ \fIfilter\fP] .HP .B cvlabel -j .RB [ \-av ] .RB [ \-F \ \fIfilter\fP] .HP .B cvlabel -c .RB [ \-T] .RB [ \-F \ \fIfilter\fP] .HP .B cvlabel .BI -C \ format .RB [ \-F \ \fIfilter\fP] .HP .B cvlabel -x .HP .B cvlabel .RB [ \-frRvw ] .RB [ \-q \ \fItag_q_depth\fP] .I label_list .HP .B cvlabel .RB [ \-fw ] .BI \-u \ VolumeName .HP .B cvlabel .RB [ \-fw ] .BI \-U \ DeviceName .HP .B cvlabel .BI \-D \ VolumeName .ad .hy .SH DESCRIPTION \fBcvlabel\fR is used when configuring the \fIXsan File System\fR disks. One host that has visibility to all the storage area network disk devices must create a list of disk labels, their associated device names and optionally the sectors to use. The .BR mount_acfs (8) process uses the volume labels to determine which disk drive is to be used for \fIXsan\fR storage pool nodes. The label name that is written to a disk device must match the \fB[Disk ...]\fR name in the \fIFile System Manager (FSM)\fR configuration. See .BR snfs_config (5) for details of the FSM configuration file. .PP It is recommended to first use \fBcvlabel\fR with the \fB\-l\fR or \fB\-L\fR option. This option will present all of the usable disk devices found on the system. It will try to identify the volume label and display the results. This will help determine what disk drives are visible to the client. .PP The next step is to create the \fIlabel_list\fR file. Use \fI/System/Library/Filesystems/acfs.fs/Contents/examples/cvlabels.example\fR as a template for your file. Or, use \fBcvlabel\fR with the \fB\-c\fR option, in which case \fBcvlabel\fR will write on stdout the list of all devices found in a format compatible with a \fIlabel_list\fR file. .PP Once a \fIlabel_list\fR file has been generated it must be edited to match the desired Xsan label updates. All LUNs included in the \fIlabel_list\fR file that are not allocated to the \fIXsan File System\fR should be removed from the \fIlabel_list\fR file to prevent accidental overwriting of existing data. Once all updates to the \fIlabel_list\fR are complete cvlabel should be run using this file to apply label changes to the indicated LUNs. .PP A final option for creating a label file is to use the \fB\-C\fR option with a format string. This behaves the same as the \fB\-c\fR option, except the format string is used to build template labels. The format string uses a printf like syntax where % followed by a letter is replaced by information obtained from the storage. The available format strings are \fB%B\fR size in sectors, \fB%L\fR lun number, \fB%C\fR controller id and \fB%S\fR serial number. Care should be taken to use a format which generates unique names for devices before using the output to label them. .PP Certain RAID devices require special handling. Cvlabel uses the raid strings inquiry table to determine which devices require special handling. The default table (displayed with the \fB-R\fR option), can be overridden by a user supplied file .I /Library/Preferences/Xsan/raid-strings. Note: the \fB-R\fR option is not intended for general use and may be deprecated in the future. Only use when recommended by Apple Support. .SH OPTIONS .TP .BR -l , " -L" Use the \fB\-l\fR option (short format) or the \fB\-L\fR option (long format) to list usable disk devices on the system. .IP "\fB-j\fR" Use the \fB\-j\fR option (JSON format) to list usable disk devices on the system in a machine and human readable format. .IP "\fB\-u\fP \fIVolumeName\fP" Use the \fB\-u\fP \fIVolumeName\fP option to unlabel the specified volume. .IP "\fB\-U\fP \fIDeviceName\fP" The \fB\-U\fP \fIDeviceName\fP option is similar to the \fB-u\fP option, except that the path to the device special file is used instead of the label name. .IP "\fB-s\fR" When used in conjunction with the \fB\-l\fR option, the \fB\-s\fR option prints the disk device \fBserial #\fR, which can be used to distinguish the difference between \fBduplicate labels\fR and \fBmultiple paths\fR. .IP "\fB-g\fR" When used in conjunction with the \fB-l\fR or \fB-L\fR options, the \fB-g\fR option also prints GUID information for EFI-labeled disks. The GUID includes a timestamp and the MAC address of the node that created the label. .IP "\fB-a\fR" When used in conjunction with the \fB\-l\fR or \fB\-L\fR options, the \fB\-a\fR option also prints unusable disk devices, along with a description of why they are unusable. This is usually due to a lack of OS support for large LUNs or an unsupported disk label format. .IP "\fB\-F\fP \fIfilter\fP" When used in conjunction with the \fB\-c\fR, \fB\-C\fR, \fB\-l\fR or \fB\-L\fP options, the \fB\-F\fP \fIfilter\fP option will only list devices whose inquiry string contains the \fIfilter\fR string. .IP "\fB-v\fR" The \fB-v\fR option prints more information about the labeling process. Multiple \fB\-v\fR options accumulate, providing more information often used for debugging the label process. .IP "\fB-q\fR" The \fB-q\fR option can be used during labeling to set the Command Tag Queue Depth. By default, the Depth is set to 16. .IP "\fB-f\fR" The \fB\-f\fR option forces labeling and you will not be asked for confirmation before labeling (or unlabeling) a disk device. \fBWARNING:\fR errors in the Xsan label_list file can cause data loss. .IP "\fB-c\fR" The \fB\-c\fR option outputs a cvlabel format template file to stdout. This template file will reflect all disk devices visible to the local system. Use this template to build a cvlabel file. \fBWARNING: Be sure to edit the template file to remove all devices which you do not want labeled.\fR .IP "\fB\-T\fR" The \fB\-T\fR option can be used in conjunction with the \fB\-c\fR option to facilitate conversion of labels from the old VTOC format to the new EFI format. The output will be similar to the ordinary \fB\-c\fR output, but devices that do not need conversion or cannot be safely converted will be output as comment lines, along with explanatory text. Only convertible devices are output normally. .IP "\fB\-D\fP \fIVolumeName\fP" The \fB\-D\fP \fIVolumeName\fP option can be used to dump the label for \fIVolumeName\fR in ascii to stdout. Examining this output is useful when debugging labels. .IP \fB\-r\fR The \fB\-r\fR option can be used to force a disk to be relabeled, even if there are no changes to the label information. Normally such disks are skipped. .IP \fB\-R\fR The \fB\-R\fR option can be used to display the default raid strings inquiry table. Note that EFI labels are not supported on IRIX systems for older releases of the Xsan File System. .IP \fB\-i\fR The \fB\-i\fR option is no longer supported. Labels should be in EFI format. .IP \fB\-w\fR The \fB\-w\fR option tells cvlabel to wait for the completion of the disk scan that is requested after a disk label has been written or a volume has been unlabeled. The disk scan requests that the file system server update its internal device tables and the \fB\-w\fR option ensures that the operation has been completed. Note that a disk scan may take a number of seconds on a large SAN or a SAN that is experiencing device errors. .PP .in +0.3i \fB*WARNING* Use this program with extreme caution! Modifying a system disk's volume label may result in irreparable harm to your system. It may render the system inoperable and force you to repair the volume using the boot maintenance program. Only label disk devices which you are sure are to be used for the Xsan File System's storage area network.\fR .in -0.3i .SH FILE FORMAT You may use the \fI/System/Library/Filesystems/acfs.fs/Contents/examples/cvlabels.example\fR file as a template. .PP A label entry consists of two or three parameters on a single line. White space and comment lines are allowed. Comment lines are designated by using a pound sign (\fB#\fR) as the first non\-white space character of the line. .PP The \fIlabel_list\fR file format is as follows: .Cs \fB [ []]\fR .Ce .sp Where: .PP \fB\fR .sp .in +0.3i The \fB\fR parameter is the name of the disk as described in the \fBFSM\fR configuration file. The parameter must match a \fB[Disk ]\fR entry. .in -0.3i .PP \fB\fR .sp .in +0.3i The \fB\fR is the device name of the complete disk device. .sp \fBNOTE:\fR operating system device names may change after reboots and will differ per system. Always configure Xsan label files, and label devices in the same session. .sp On \fBWindows\fR systems, the devices start as \fBPhysicalDrive0\fR and increment up to the number of drives configured. .in -0.3i .PP \fB\fR .sp .in +0.3i The \fB\fR parameter is the number in 512-byte sectors that matches the \fB[DiskType ...]\fR configuration in the FSM configuration file. This is required for disks that must be configured smaller than their actual size. For example, MPIRE video disks must be under\-configured to eliminate using the last zone of the disk. If \fB\fR is not specified or is specified as \fB\-\fR, then the .BR cvlabel (8) program will use the entire available volume. .PP \fB\fR .sp .in +0.3i The \fB\fR parameter is used to override the default label type, or to change the label type for a disk that already has a label. The value must be \fBEFI\fR for changing a \fBVTOC\fR label to an \fBEFI\fR label. .in -0.3i .PP .SH EXAMPLES List all the disk devices in a system. .Cs rock # cvlabel -L /dev/sda [ATA ST500NM0011 PA08] MBR Controller 'default', Serial '5000C5004FDC5C85', Sector Size 512, Sectors Max 976754703 (500.1GB) /dev/mapper/mpathai [Quantum StorNext QX H205] SNFS-EFI "dexter1d1" Controller '208000C0FF193C0F', Serial '600C0FF00014658335219B5801000000', Sector Size 512, Sectors 39030873055 (20.0TB), Stripebreadth 0 [...] /dev/mapper/mpathap [DotHill DH4730 H205] unknown Controller '208000C0FF155519', Serial '600C0FF00019B6162739A65801000000', Sector Size 512, Sectors 18554669023 (9.5TB) [...] /dev/mapper/mpathan [Quantum QXS G22x] SNFS-EFI "snfs_data_bh-5600-1_L5" Controller '208000C0FF25E3DB', Serial '600C0FF0001BE2E0C9D94E5701000000', Sector Size 512, Sectors 140511467487 (71.9TB), Stripebreadth 3145728 .Ce .PP Then create a template label file: .Cs rock # cvlabel -c >label_list .Ce .PP The output file will include an entry for the 'unknown' disk: .Cs CvfsDisk_UNKNOWN /dev/mapper/mpathao # host 0 lun 3 sectors 18554669023 sector_size 512 inquiry [DotHill DH4730 H205] serial 600C0FF00019B6165E39A65801000000 .Ce .PP Edit the \fIlabel_list\fR file, changing \fBCvfsDisk_UNKNOWN\fR to the desired label name: .Cs CvfsDisk_39 /dev/mapper/mpathao .Ce .PP Now label the disk devices. Your \fIlabel_list\fR file must be specified on the command line. .Cs rock # cvlabel \fIlabel_list\fR *WARNING* This program will over-write volume labels on the devices specified in the file \fIlabel_list\fR. After execution, the devices will only be usable by the Xsan File System. You will have to re-partition the devices to use them on a different file system. Do you want to proceed? (Y / N) -> y /dev/mapper/mpathap [DotHill DH4730 H205] unknown Controller '208000C0FF155519', Serial '600C0FF00019B6162739A65801000000', Sector Size 512, Sectors 18554669023 (9.5TB) Do you want to label it SNFS-EFI - Name: CvfsDisk_39 Sectors: 18554669023 (Y / N) -> y New Volume Label -Device: /dev/mapper/mpathap SNFS Label: CvfsDisk_39 Sectors: 18554669023. Done. 1 source lines. 1 labels. .Ce .PP The labels are done. List the disk devices again. .PP .Cs rock # cvlabel -L /dev/sda [ATA ST500NM0011 PA08] MBR Controller 'default', Serial '5000C5004FDC5C85', Sector Size 512, Sectors Max 976754703 (500.1GB) /dev/mapper/mpathai [Quantum StorNext QX H205] SNFS-EFI "dexter1d1" Controller '208000C0FF193C0F', Serial '600C0FF00014658335219B5801000000', Sector Size 512, Sectors 39030873055 (20.0TB), Stripebreadth 0 [...] /dev/mapper/mpathap [DotHill DH4730 H205] SNFS-EFI "CvfsDisk_39" Controller '208000C0FF155519', Serial '600C0FF00019B6162739A65801000000', Sector Size 512, Sectors 18554669023 (9.5TB) [...] /dev/mapper/mpathan [Quantum QXS G22x] SNFS-EFI "snfs_data_bh-5600-1_L5" Controller '208000C0FF25E3DB', Serial '600C0FF0001BE2E0C9D94E5701000000', Sector Size 512, Sectors 140511467487 (71.9TB), Stripebreadth 3145728 .Ce .PP Generate a label file of all LSI storage which uses the controller serial number and lun numbers as components of the labels. .PP .Cs rock # cvlabel -C CVFS_%S_%L -F LSI > label_list .Ce .PP Display to stdout the default raid strings inquiry table. .Cs rock # cvlabel -R # Raid inquiry string table # Controls interpretation of raid mode pages based on inquiry strings # # Allowed types: # LSI LSI (Engenio) Raid in AVT mode # Clariion Clariion (EMC) Raid in Auto trespass mode # Seagate Dual port Seagate JBODs # JBOD No special handling (Real JBOD or RDAC driver) # Quantum StorNext QX # Quantum QXS # String 1 String 2 Raid Type "DGC" "" Clariion "ENGENIO" "" LSI "IBM" "1722-600" LSI "IBM" "1742-900" LSI "IBM" "1814" LSI "IBM" "Universal Xport" LSI "LSI" "VirtualDisk" JBOD "LSI" "MegaRAID" JBOD "LSI" "ProFibre" JBOD "LSI" "Universal Xport" LSI "NETAPP" "Universal Xport" LSI "ENGENIO" "Universal Xport" LSI "LSI" "" LSI "SGI" "TP9300" LSI "SGI" "TP9400" LSI "SGI" "TP9500" LSI "SGI" "TP9700" LSI "SGI" "IS600" LSI "SGI" "IS500" LSI "SGI" "IS400" LSI "SGI" "IS300" LSI "STK" "FLEXLINE" LSI "STK" "OPENstorage" LSI "STK" "Universal Xport" LSI "STK" "BladeCtlr" LSI "Quantum StorNext QX" "" QX "Quantum QXS" "" QX "SEAGATE" "" Seagate .Ce .PP Use the default raid strings inquiry table to seed a user-defined table. .Cs rock # cvlabel -R > /Library/Preferences/Xsan/raid-strings .Ce .SH NOTES .PP Some operating systems require a reboot after a disk is labeled or relabeled. It is recommended that Xsan nodes are rebooted after new labels are written or existing labels are updated. .SH FILES .I /System/Library/Filesystems/acfs.fs/Contents/examples/cvlabels.example .br .I /System/Library/Filesystems/acfs.fs/Contents/examples/example.cfgx .br .I /Library/Preferences/Xsan/raid-strings .SH "SEE ALSO" .BR cvfs (8), .BR snfs_config (5), .BR mount_acfs (8)