======== Mounting ======== .. image:: pic/mounting-schema.svg .. :width: 90% .. note:: Currently, only basic mounting/unmounting works. Persistency, mount flags (i.e. bind) and mount options are not implemented, yet. These limitations will be addressed in the future releases. Every mount is represented by an :ref:`LMI_MountedFileSystem ` instance. Each instance can have one or two :ref:`LMI_MountedFileSystemSetting ` instances associated to it via :ref:`LMI_MountedFileSystemElementSettingData ` (one for the currently mounted filesystem and one for a persistent entry in /etc/fstab). This association class has two important properties -- *IsCurrent* and *IsNext*. Their meaning is described in detail in the `On modes`_ section. :ref:`LMI_MountedFileSystemSetting ` is used for representing mount options (e.g. whether to mount read-write or read-only). The setting instance can also exists on its own. This means that its not connected with :ref:`LMI_MountedFileSystem ` by any association. Such situation can happen when there is an :ref:`LMI_MountedFileSystem ` instance with two distinctive setting instances attached to it (one with IsNext = 1 and one with IsCurrent = 1). After DeleteMount() with a parameter of mode = 32769 (only unmounts) is called, the respective association between the setting and mounted filesystem instances is removed, but the setting instance itself stays in the system. Local filesystems, both supported and unsupported, are represented by :ref:`LMI_LocalFileSystem ` class and its subclasses. Filesystems are associated to :ref:`LMI_MountedFileSystem ` via :ref:`LMI_AttachedFileSystem ` . .. note:: Currently, only local filesystems are supported. When a filesystem is currently mounted, the directory where the :ref:`LMI_MountedFileSystem ` instance is attached at is represented by an :ref:`LMI_UnixDirectory ` instance. These two instances are connected through an :ref:`LMI_MountPoint ` association instance. The following diagram shows a local ext4 partition /dev/sda2 currently mounted at /boot. The filesystem is specified by its UUID. No persitent entry in /etc/fstab is managed. .. image:: pic/mounting-instance.svg The next figure shows a local ext3 partition /dev/sda1 mounted at /home and also made persistent in /etc/fstab, both with slightly different settings. The filesystem is specified by its UUID. .. image:: pic/mounting-instance-2.svg The final diagram represents a state where a local ext4 partition /dev/sda4, filesystem of which is specified by its UUID, is mounted at /var/log and also has the respective entry written in /etc/fstab. Note that both settings (current mount and the persistent entry) are the same, as is indicated by IsNext and IsCurrent being set to 1. .. image:: pic/mounting-instance-3.svg .. note:: TODO: bind mount examples, remote fs examples Using the mounting API ====================== On modes -------- When calling CreateMount() or DeleteMount() methods, one of their arguments is a mode. The mode is an enumeration that denotes values of two different properties of the LMI_MountedFileSystemElementSettingData association. They are **IsNext** and **IsCurrent**. They determine if the mount operation performs mount only, adds a persisten entry to /etc/fstab, or both. The following table displays possible values and their respective meanings of IsNext and IsCurrent. .. table:: +-----------+-------+-------------------------------------------------------------------------------+ | | Value | Meaning | +===========+=======+===============================================================================+ | | 1 | In mounting this means persistency, an entry in /etc/fstab. | | IsNext +-------+-------------------------------------------------------------------------------+ | | 2 | No entry in /etc/fstab. | +-----------+-------+-------------------------------------------------------------------------------+ | | 1 | Currently, the device is mounted. Can be thought of as an entry in /etc/mtab. | | IsCurrent +-------+-------------------------------------------------------------------------------+ | | 2 | The device is not mounted. | +-----------+-------+-------------------------------------------------------------------------------+ **Supported modes** and their meaning are the following mode. .. table:: ======== =============== =============== Mode IsNext IsCurrent ======== =============== =============== 1 1 1 2 1 Not affected. 4 2 2 5 2 Not affected. 32768 Not affected. 1 32769 Not affected. 2 ======== =============== =============== Methods ------- :ref:`CreateMount ` Mounts a device to the specified mountpoint. :ref:`ModifyMount ` Modifies (remounts) the specified filesystem. :ref:`DeleteMount ` Unmounts the specified filesystem. All the methods are asynchronous. DeleteMount() note ------------------ If, after DeleteMount(), IsNext and IsCurrent are both set to 2 (device was unmounted and its persistent entry removed), the corresponding :ref:`LMI_MountedFileSystem ` , :ref:`LMI_MountedFileSystemSetting ` and their association are removed. This implies that there cannot be any :ref:`LMI_MountedFileSystemElementSettingData ` with both IsNext and IsCurrent set to 2. Use cases ========= Typical use of the mounting API could be like the following: Use an :ref:`LMI_MountedFileSystemCapabilities ` instance to create a setting instance using the :ref:`CreateSetting ` method. This method creates an instance of :ref:`LMI_MountedFileSystemSetting ` class with default property values. Modify the setting instance as needed. This is done using the :ref:`ModifyMount ` intrinsic method. This step is optional if the admin is satisfied with the default set of values. Use an :ref:`LMI_MountConfigurationService ` to create a mount using the CreateMount() method or modify a mount using the ModifyMount() method. You can also use an :ref:`LMI_MountConfigurationService ` to unmount a mount using the DeleteMount(). .. note:: The example scripts below are written using the OpenLMI shell. Note that as of now, the shell does not support some of the features needed for the complete example (e.g. correct support for jobs). * TODO: More examples (persistency, bind mount, replace line in /etc/fstab, nfs mount) Example 1 --------- This example demonstrates mounting a partition with a customized setting. :: c = connect('localhost', 'root', 'mypassword') ns = c.root.cimv2 # step 1 - create an LMI_MountedFileSystemSetting instance (rc, out, err) = cap.CreateSetting() if rc != 0: raise # step 2 - modify the setting instance set.AllowWrite = False set.InterpretDevices = False set.push() # step 3 - mount # if Goal == None, the defaults will be used # Mode == 32768 -> only mount fs = ns.LMI_LocalFileSystem.first_instance(key="Name", value="UUID=330d61f7-9cdc-416b-9995-25ff78d5776c") (rc, out, err) = ser.CreateMount(Goal=set_name.path, FileSystemType='ext4', Mode=32768, FileSystem=fs.path, MountPoint='/mnt', FileSystemSpec='/dev/vda1' ) # 0 - Completed with no error # 4096 - Method parameters checked, job started if not (rc == 0 or rc == 4096): raise job_name = out['Job'] job = job_name.to_instance() # wait for the job here... # but since we mount only locally, we can check the job right away # check if the job completed without any errors # if not, display the error message # JobState == 7 -> Completed if job.JobState != 7: # lmishell can't do this yet # job.GetErrors() print "NOT mounted." else: print "Mounted successfully." Example 2 --------- In this example, /mnt mounted in Example 1 is unmounted. :: c = connect('localhost', 'root', 'mypassword') ns = c.root.cimv2 ser = ns.LMI_MountConfigurationService.first_instance(key="Name", value="LMI_MountConfigurationService") mnt = ns.LMI_MountedFileSystem.first_instance(key="MountPointPath", value="/mnt") if not mnt: raise BaseException("Mountpoint does not exist: /mnt") (rc, out, err) = ser.DeleteMount(Mount=mnt.path, Mode=32769 ) # 0 - Completed with no error # 4096 - Method parameters checked, job started if not (rc == 0 or rc == 4096): raise job_name = out['Job'] job = job_name.to_instance() # we should wait for the job here... lmishell can't do this yet # check if the job completed without any errors # if not, display the error message # JobState == 7 -> Completed if job.JobState != 7: # lmishell can't do this yet # job.GetErrors() print "NOT unmounted." else: print "Unmounted successfully."