.\" xsanctl.8: auto-generated, DO NOT EDIT .\" .\" .\" Copyright (c) 2007, 2009, 2011, 2015 Apple Inc. All rights reserved. .\" .Dd April 20, 2015 .Dt XSANCTL 8 .Os Xsan .Sh NAME .Nm xsanctl .Nd Xsan file system control utility .Sh SYNOPSYS .Nm .Ar command .Op Ar arg Op ... .Sh DESCRIPTION .Nm provides a basic control facility for the Xsan file system. It operates by sending commands to the Xsan file system management daemon .Nm xsand . .Nm must be run by the superuser. .Sh COMMANDS .Nm provides the following commands: .Ss Primary commands These commands are the primary ones needed for SAN management. .Bl -tag -width XXunmountXX .It Ic help Display a list of the available .Nm commands. .It Ic ping Sends a .Sq ping message to .Nm xsand . This can be used to verify that .Nm xsand is responding to management requests. .It Ic mount Ar volumeName [options] Creates the volume mount device for volume .Ar volumeName . If any mount options are given, .Nm xsand updates the local mount options for the volume before creating the volume mount device. .Nm diskarbitrationd will mount the volume after the volume mount device is created. This is the preferred method of mounting Xsan volumes from the command line. .Pp .Ar [options] include those options recognized by .Nm mount_acfs and three others: --at Specify a non-standard path at which to mount the volume. --rw Mount the volume for both reading and writing. This behavior is the default. --ro Mount the volume read-only. --clusteriosize=size Specify the maximum I/O transfer size (in bytes) that the cluster layer can submit to the file system's IO strategy routine. The minimum value allowed is 1MB and the maximum value allowed is 32MB. The default value is set to 8MB when the option is not specified. .Nm mount_acfs options should be preceded by two dashes. For instance, the number of kernel threads will increase to twenty as a result of this option: .Ar --threads=20 . .It Ic unmount Ar volumeName [options] Unmounts the volume .Ar volumeName . --force Force the unmount. This operation may cause data loss Previous versions of Xsan explicitly forced mounting of selected volumes. This version of Xsan creates volume mount devices for all on-line and connected volumes and leaves mount state control to disk arbitration. .It Ic list Displays a list of the available volumes. .It Ic createSan Ar sanName [createMaster arguments] This subcommand must be run as root and does not depend on xsand running. This subcommand creates a new SAN with this computer as the only controller. The SAN's name is .Ar sanName and may not begin with a dash. This subcommand has two variants. In both forms, it creates a new Xsan SAN. The subcommand's behavior depends on the configuration state of .Nm Open Directory when it runs. .Nm Xsan controllers must be .Nm Open Directory controllers for the cluster containing the SAN configuration. If the computer is not an .Nm Open Directory controller this subcommand configures the computer to be the master of a new .Nm Open Directory cluster, and then creates the SAN using that cluster. .Pp The subcommand options supplied after the SAN name are examined in the case where the computer is not an .Nm Open Directory controller. In this case, they are processed as if the .Nm createMaster subcommand had been run. In the case where the computer is already an .Nm Open Directory controller, none of the additional command options are valid. .It Ic listSan Displays a list of available Xsan SANs in the local network. This subcommand does not depend on xsand running. .It Ic joinSan Ar sanName [options] [createReplica arguments] This subcommand must be run as root and does not depend on xsand running. This subcommand joins this computer with an existing SAN as a metadata controller. This computer will be an additional metadata controller for an existing SAN. The subcommand's behavior depends on the configuration state of .Nm Open Directory when it runs. .Nm Xsan controllers must be .Nm Open Directory controllers for the cluster containing the SAN configuration. If the computer is not an .Nm Open Directory controller, this subcommand configures the computer to be a replica in the .Nm Open Directory cluster, and then joins the SAN using that cluster. .Pp The subcommand options supplied after the joinSAN options are examined in the case where the computer is not an .Nm Open Directory controller. In this case, they are processed as if the .Nm createReplica subcommand had been run. In the case where the computer is already an .Nm Open Directory controller, none of the additional .Nm createReplica command options are valid. --controller-name .Ar ControllerName Specify the metadata controller name in the SAN in which this computer wants to join. --controller-user .Ar ControllerUserName Specify the administrator name for the metadata controller in which this computer wants to join. --controller-pass .Ar ControllerPassword Specify the administrator password for the metadata controller in which this computer wants to join. .It Ic leaveSan This subcommand must be run as root and does not depend on xsand running. This subcommand removes this computer as a metadata controller from an existing SAN. .It Ic removeControllerFromSan Ar controllerName This subcommand removes the specified computer as a metadata controller from an existing SAN. .It Ic destroySan This subcommand must be run as root and does not depend on xsand running. This subcommand sets the SAN configuration for this system's SAN to dead and updates the configuration in LDAP. It also posts a configuration update message to the SAN. Note: this command does NOT gracefully stop the SAN. Controllers and clients may need to be rebooted if they do not cleanly stop. Use with care. This operation can not be undone. .It Ic exportClientProfile Exports Xsan configuration profile which can be installed on clients with Profile Manager. --path .Ar dirPath Specify the directory path in which the configuration profile will be created. If this option is not selected, the current working directory path will be used. --output .Ar outputFile Specify the file name to use for the configuration profile. If this option is not selected, the name of the SAN will be used as a default. .It Ic addVolume Ar volumeName [addOrEditVolumeOptions] This subcommand creates a new volume named .Ar volumeName . The command options used to describe a new volume's format are described in the .Sx VOLUME DESCRIPTION section below. The volume will be hosted on all current controllers, and will be started after creation. A new volume will consist of one or more Storage pools. One or more Storage pools must contain .Ar metadata , One or more Storage pools must contain .Ar userdata , and exactly one Storage pool must contain the .Ar journal . .It Ic editVolume Ar volumeName [addOrEditVolumeOptions] This subcommand edits the settings for an existing volume named .Ar volumeName . The command options used to describe volume's settings are described in the .Sx VOLUME DESCRIPTION section below. Many of the volume settings set at .Cm addVolume time may be subsequently changed. The ones which can not are documented in that section. This subcommand can also add new Storage pools to the volume. .It Ic dropVolume Ar [option] volumeName Removes a volume from SAN. This subcommand must be run as root. Note: the clients may need to be rebooted if '--force' option fails to cleanly stop the clients. --force Force the deletion even the volume is still mounted by the clients .It Ic startVolume Ar volumeName Start the volume .Ar volumeName . This subcommand must be run as root. .It Ic stopVolume Ar [option] volumeName Stops the volume .Ar volumeName . Further operations to the volume will be blocked in clients until the volume is started. This subcommand must be run as root. --force Force the stop even the volume is still mounted by the clients .It Ic dumpVolumeConfig Ar [option] Prints the Xsan volume configuration(s) hosted on the local machine as JSON. --volume The name of the volume to print. If specified, only the volume with the same name will get printed. .It Ic unloadProfile This subcommand must be run as root and does not depend on xsand running. This subcommand unloads any profiles configuring Xsan which were not installed by Profile Manager. Profile removal will wipe the local Xsan configuration. .El .Ss Secondary commands These commands are less-frequently used commands for SAN management. .Bl -tag -width XXunmountXX .It Ic changeIP Ar oldIP newIP [oldHostName newHostName] This subcommand must be run as root. This subcommand changes the SAN configuration locally and in LDAP if the current Xsan address is .Ar oldIP . .Ar newIP is used in its place. If the fully-qualified domain name .Ar oldHostName is also passed as an arguement, the host name retained in the LDAP configuration for this host is changed to .Ar newHostName . Please ensure that all controllers have the SSL certificate for .Ar newHostName before running this command. Changing the host name of a controller will cause all clients in the SAN to re-read the controller certificates. .It Ic createMaster Creates a new master LDAP server and a new directory node administrator. --cert-auth-name .Ar CertAuthName Specify the name to be used for Certificate Authority. --cert-admin-email .Ar CertAdminEmail Specify the email address to be used for Certificate Authority admin. --user .Ar AdminFullName Specify the full name for the new administrator account. --account .Ar AdminAccountShortName Specify the username for the new administrator account. --pass .Ar AdminPassword Specify the password for the new administrator account. .It Ic createReplica Creates a new replica from an existing LDAP master and joins Open Directory. --master .Ar MasterAddress Specify the LDAP master IP address or name. --account .Ar AdminAccountShortName Specify the username for the administrator account. --pass .Ar AdminPassword Specify the password for the administrator account. .It Ic destroyMaster Turns off the LDAP server and deletes its database. --account .Ar AdminAccountShortName Specify the username for the administrator account. --pass .Ar AdminPassword Specify the password for the administrator account. .It Ic destroyReplica Unjoins Open Directory and removes a replica from an existing LDAP master. --account .Ar AdminAccountShortName Specify the username for the administrator account. --pass .Ar AdminPassword Specify the password for the administrator account. .It Ic activateSan [createReplica arguments] This subcommand must be run as root and does not depend on xsand running. This subcommand activates the previous Xsan SAN configuration after macOS upgrade. On secondary MDC, the subcommand's behavior depends on the configuration state of .Nm Open Directory when it runs. .Nm Xsan controllers must be .Nm Open Directory controllers for the cluster containing the SAN configuration. If the computer is not an .Nm Open Directory controller, this subcommand configures the computer to be a replica in the .Nm Open Directory cluster, and then activates the previous Xsan SAN configuraton. .Pp The subcommand options supplied are examined in the case where the computer is not an .Nm Open Directory controller. In this case, they are processed as if the .Nm createReplica subcommand had been run. In the case where the computer is already an .Nm Open Directory controller, none of the additional .Nm createReplica command options are valid. .It Ic cullSan Ar sanName This subcommand must be run as root and does not depend on xsand running. This subcommand destroys the LDAP configuration for a SAN. This subcommand is intended to clean up SAN configurations in LDAP which have been in the dead state long enough that all clients have been unconfigured. This operation can not be undone. .It Ic disksChanged Sends a notification to the Xsan file system that disks have changed and should be rescanned. .It Ic eraseVolume Ar volumeName Initializes the volume .Ar volumeName . .Pp See .Sx CAUTION section below. .It Ic renameVolume Ar oldName newName Renames an existing volume name to the new name. The existing config file will be renamed, and the existing data directory containing logs will be migrated to the new name. This subcommand must be run as root. .It Ic importVolume Ar volumeConfigFile Imports a volume into SAN using the specified volume config file. Upon successful import, the volume will be started. .It Ic dumpLdapConfig Prints the SAN configuration. --json Print the configuration in JSON. .El .Ss Plumbing commands These commands expose specific points of SAN management functionality. They can be very powerful, and offer an administrator a lot of flexibility. Use these commands with care as they offer enough flexibility to trip and/or harm an administrator. .Bl -tag -width XXunmountXX .It Ic sanConfigChanged Sends a notification to the Xsan file system that the SAN configuration has changed and should be reloaded. .It Ic pushConfigUpdate Pushes out a new configuration update. This subcommand must be run as root and does not depend on xsand running. This subcommand adjusts the SAN configuration in ldap to match the configuration status in /Library/Preferences/Xsan. If the ldap configuration is changed, a configuration update message will be posted to the SAN. .Pp See .Sx CAUTION section below. .It Ic ldapConfigChanged This subcommand must be run as root and does not depend on xsand running. This subcommand verifies the local configuration with the configuration in ldap, and updates the local configuration to match. .Pp See .Sx CAUTION section below. .It Ic roleChanged Sends a notification to the Xsan file system that the role has changed. .It Ic wipeConfig Causes the Xsan file system configuration to be reset to an unconfigured state. .It Ic listTask Ar volumeName [options] List the long running task for .Ar volumeName . .Fl -cleanup Cleanup the long running task if it has been completed. .Fl -wait Wait for the long running task to complete. .It Ic listTasks List all long running tasks for all volumes. .El .Sh VOLUME DESCRIPTION The .Ic addVolume and .Ic editVolume verbs share the command options below. Most options are available to both verbs. A few are only available to .Ic addVolume as they control settings which can not be modified by .Ic editVolume . .Ss VOLUME SETTINGS .Bl -tag -width XXmount .It Fl -caseSensitive Enable case sensitive on Xsan file system. When enabled, the volume considers filenames to be .Ar different if they are spelled alike but capitalized differently. .It Fl -caseInsensitive Enable case insensitive on Xsan file system. When enabled, the volume considers filenames to be the .Ar same if they are spelled alike but capitalized differently. This setting is the default for new volumes. .It Fl -enableACLs Specify whether the Xsan file system uses access control lists (ACLs) on a volume. .It Fl -ignoreOwners Enable the noowners flag when mounting the volume, as documented in the .Ic mount(8) man page. This setting is the default for new volumes. .It Fl -idsFromGUIDs Specify that Windows clients should dynamically generate UIDs and GIDs based on globally unique identifer (GUID) information in Active Directory domain when mapping user and group information to Xsan-compatible user IDs (UIDs) and group IDs (GIDs). .It Fl -idsFromLDAP Specify that Windows clients should get UID and GID values from the uidNumber and gidNumber attributes in Active Directory records when mapping user and group information to Xsan-compatible user IDs (UIDs) and group IDs (GIDs). This setting is the default for new volumes. .It Fl -noExtendedAttrs Disable support for Apple Named Streams. Named Streams are utilized by Apple Xsan clients. Disabling support on a Xsan file system is a permanent change. It cannot be enabled once disabled. .El .Ss STORAGE POOL SETTINGS An Xsan volume contains one or more LUNs grouped into one or more .Ar Storage Pools . A Storage Pool's description begins with a .Fl -storagePool argument which specifies the Storage Pool's name. Subsequent arguments control the content stored in the pool and add LUNs to the pool. A pool's description ends when a subsequent . Fl -storagePool argument starts the next pool, or the command line ends. Storage Pool names must be unique within the volume. .Pp As every volume requires one pool containing metadata and the journal, the .Fl -defaultFirstPool argument facilitates quickly creating such a Storage Pool. This argument is equivalent to this sequence of command arguments: .Cm --storagePool MetadataAndJournal --metadata --journal Further, this Storage Pool is placed at the beginning of the Storage Pool list, regardless of where this argument is located in the command line. For typical usage, the only arguments needed for this storage pool are to add one or more LUNs to the pool. .Pp If none of the content types are set on a Storage Pool, it defaults to contain userdata. .Bl -tag -width XXmount .It Cm --storagePool StoragePoolName Begin specifying a storage pool named .Ar StoragePoolName . This argument implicitly ends any preceding Storage Pool description. .It Cm --defaultFirstPool Begin specifying a storage pool named .Ar MetadataAndJournal which contains the journal and metadata. This Storage Pool is placed at the beginning of the Storage Pool list, regardless of where this argument is located on the command line. This argument implicitly ends any preceding Storage Pool description. .It Fl -metadata This Storage Pool may contain metadata. .It Fl -journal This Storage Pool will contain the journal. .It Fl -data This Storage Pool may contain userdata. .It Fl -any Shorthand for specifying .Fl -metadata -data -journal .It Cm --addLUN DiskLabelName Add a disk to the Storage Pool. The Disk Label name can be determined using using .Ic cvlabel command. .It Cm --addLUNs Disk1LabelName,Disk2LabelName,... Add multiple disks to the Storage Pool. .It Cm --stripeBreadth StripeBreadthSizeInKB Specify the amount of data that will be written to a LUN before switching to the next LUN within a stripe group. For optimal performance, .Nm stripeBreadth size should be a multiple of RAID stripe size. The .Nm stripeBreadth size must also be a multiple file system block size of 4096 bytes. .El .Ss COMMAND SETTINGS .Bl -tag -width XXmount .It Fl -dry-run Verify the requested operation without actually applying the changes. .It Fl -output Write the volume configuration settings to the specified output path. This option is intended exclusively for automated testing. This option is subject to change without notice. .It Fl --non-interactive Perform the requested operation without actually waiting for its completion. The status of the operation can later be queried using the .Ic listTask or .Ic listTasks verbs. This option is intended exclusively for automated testing. This option is subject to change without notice. .El .Ss EXAMPLES .Bl -tag -width XXmount .It Cm addVolume superVolume --defaultFirstPool --addLUN metaLUN --storagePool lotsOfSpace --addLUNs firstAcreOfData,secondAcreOfData This command creates a new volume, .Ar superVolume with two Storage Pools, .Ar MetadataAndJournal and .Ar lotsOfSpace . The first Storage Pool is the one named .Ar MetadataAndJournal and contains metadata and the journal. This storage pool contains one LUN named .Ar metaLUN . The second Storage Pool is named .Ar lotsOfSpace and contains userdata due to the use of the default userdata specification. This Storage Pool contains two LUNs named .Ar firstAcreOfData and .Ar secondAcreOfData . .It Cm addVolume superVolume --storagePool lotsOfSpace --addLUNs firstAcreOfData,secondAcreOfData --defaultFirstPool --addLUN metaLUN This command creates the same volume as before, and demonstrates how the Storage Pool created by .Fl -defaultFirstPool is always the first Storage Pool in the volume, regardless of where the argument is on the command line. .It Cm editVolume superVolume --caseSensitive Change the volume .Ar superVolume to be case sensitive. .It Cm editVolume superVolume --storagePool moreSpace --addLUNs thirdAcreOfData,fourthAcreOfData Add a new Storage Pool named .Ar moreSpace to the volume .Ar superVolume . This Storage Pool will contain two LUNs named .Ar thirdAcreOfData and .Ar fourthAcreOfData . .El .Sh CAUTION The .Ic pushConfigUpdate and .Ic ldapConfigChanged verbs can permanently damage a SANs configuration when run on a controller if LDAP replication is not functioning correctly. These verbs assume that the local LDAP node contains a correct configuration for the SAN, and can lose data if this assumption is incorrect. .Pp The .Ic pushConfigUpdate verb especially can be dangerous if the local LDAP configuration is not current. Any local differences between it and the state in the /Library/Preferences/Xsan configuration files will trigger an update to the local LDAP which the SAN will then take as the most-up-to-date configuration. .Pp Specifically, if a volume has been created in the SAN but it is not described in the LDAP configuration of a controller executing .Ic pushConfigUpdate , this volume's configuration will be lost and any controller currently hosting it will stop. Clients will not correctly disconnect and thus require a hard reboot. .Pp The .Ic eraseVolume verb will destroy ALL existing data in the volume. .Sh SEE ALSO .Xr diskutil 8 , .Xr launchd 8 , .Xr cvadmin 8 , .Xr cvlabel 8 , .Xr xsand 8 , .Xr mount 8