| SCST SYSFS interface rules |
| ========================== |
| |
| This file describes SYSFS interface rules, which all SCST target |
| drivers, dev handlers and management utilities MUST follow. This allows |
| to have a simple, self-documented, target drivers and dev handlers |
| independent management interface. |
| |
| Words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", |
| "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this |
| document are to be interpreted as described in RFC 2119. |
| |
| In this document "key attribute" means a configuration attribute with |
| not default value, which must be configured during the target driver's |
| initialization. A key attribute MUST have in the last line keyword |
| "[key]". If a default value set to a key attribute, it becomes a regular |
| none-key attribute. For instance, iSCSI target has attribute DataDigest. |
| Default value for this attribute is "None". It value "CRC32C" is set to |
| this attribute, it will become a key attribute. If value "None" is again |
| set, this attribute will become back to a none-key attribute. |
| |
| Each user configurable attribute with a not default value MUST be marked |
| as key attribute. |
| |
| Key attributes SHOULD NOT have sysfs names finished on digits, because |
| such names SHOULD be used to store several attributes with the same name |
| on the sysfs tree where duplicated names are not allowed. For instance, |
| iSCSI targets can have several incoming user names, so the corresponding |
| attribute should have sysfs name "IncomingUser". If there are 2 user |
| names, they should have sysfs names "IncomingUser" and "IncomingUser1". |
| In other words, all "IncomingUser[0-9]*" names should be considered as |
| different instances of the same "IncomingUser" attribute. |
| |
| |
| I. Rules for target drivers |
| =========================== |
| |
| SCST core for each target driver (struct scst_tgt_template) creates a |
| root subdirectory in /sys/kernel/scst_tgt/targets with name |
| scst_tgt_template.name (called "target_driver_name" further in this |
| document). |
| |
| For each target (struct scst_tgt) SCST core creates a root subdirectory |
| in /sys/kernel/scst_tgt/targets/target_driver_name with name |
| scst_tgt.tgt_name (called "target_name" further in this document). |
| |
| There are 2 type of targets possible: hardware and virtual targets. |
| Hardware targets are targets corresponding to real hardware, for |
| instance, a Fibre Channel adapter's port. Virtual targets are hardware |
| independent targets, which can be dynamically added or removed, for |
| instance, an iSCSI target, or NPIV Fibre Channel target. |
| |
| A target driver supporting virtual targets MUST support "mgmt" attribute |
| and "add_target"/"del_target" commands. |
| |
| If target driver supports both hardware and virtual targets (for |
| instance, an FC adapter supporting NPIV, which has hardware targets for |
| its physical ports as well as virtual NPIV targets), it MUST create each |
| hardware target with hw_target mark to make SCST core create "hw_target" |
| attribute (see below). |
| |
| Attributes for target drivers |
| ----------------------------- |
| |
| A target driver MAY support in its root subdirectory the following |
| optional attributes. Target drivers MAY also support there other |
| read-only or read-writable attributes. |
| |
| 1. "enabled" - this attribute MUST allow to enable and disable target |
| driver as a whole, i.e. if disabled, the target driver MUST NOT accept |
| new connections. The goal of this attribute is to allow the target |
| driver's initial configuration. For instance, iSCSI target may need to |
| have discovery user names and passwords set before it starts serving |
| discovery connections. |
| |
| This attribute MUST have read and write permissions for superuser and be |
| read-only for other users. |
| |
| On read it MUST return 0, if the target driver is disabled, and 1, if it |
| is enabled. |
| |
| On write it MUST accept '0' character as request to disable and '1' as |
| request to enable, but MAY also accept other driver specific commands. |
| |
| During disabling the target driver MAY close already connected sessions |
| in all targets, but this is OPTIONAL. |
| |
| MUST be 0 by default. |
| |
| 2. "trace_level" - this attribute SHOULD allow to change log level of this |
| driver. |
| |
| This attribute SHOULD have read and write permissions for superuser and be |
| read-only for other users. |
| |
| On read it SHOULD return a help text about available command and log levels. |
| |
| On write it SHOULD accept commands to change log levels according to the |
| help text. |
| |
| For example: |
| |
| out_of_mem | minor | pid | line | function | special | mgmt | mgmt_dbg | flow_control | conn |
| |
| Usage: |
| echo "all|none|default" >trace_level |
| echo "value DEC|0xHEX|0OCT" >trace_level |
| echo "add|del TOKEN" >trace_level |
| |
| where TOKEN is one of [debug, function, line, pid, |
| entryexit, buff, mem, sg, out_of_mem, |
| special, scsi, mgmt, minor, |
| mgmt_dbg, scsi_serializing, |
| retry, recv_bot, send_bot, recv_top, |
| send_top, d_read, d_write, conn, conn_dbg, iov, pdu, net_page] |
| |
| |
| 3. "version" - this read-only for all attribute SHOULD return version of |
| the target driver and some info about its enabled compile time facilities. |
| |
| For example: |
| |
| 2.0.0 |
| EXTRACHECKS |
| DEBUG |
| |
| 4. "mgmt" - if supported this attribute MUST allow to add and delete |
| targets, if virtual targets are supported by this driver, as well as it |
| MAY allow to add and delete the target driver's or its targets' |
| attributes. |
| |
| This attribute MUST have read and write permissions for superuser and be |
| read-only for other users. |
| |
| On read it MUST return a help string describing available commands, |
| parameters and attributes. |
| |
| To achieve that the target driver should just set in its struct |
| scst_tgt_template correctly the following fields: mgmt_cmd_help, |
| add_target_parameters, tgtt_optional_attributes and |
| tgt_optional_attributes. |
| |
| For example: |
| |
| Usage: echo "add_target target_name [parameters]" >mgmt |
| echo "del_target target_name" >mgmt |
| echo "add_attribute <attribute> <value>" >mgmt |
| echo "del_attribute <attribute> <value>" >mgmt |
| echo "add_target_attribute target_name <attribute> <value>" >mgmt |
| echo "del_target_attribute target_name <attribute> <value>" >mgmt |
| |
| where parameters are one or more param_name=value pairs separated by ';' |
| |
| The following target driver attributes available: IncomingUser, OutgoingUser |
| The following target attributes available: IncomingUser, OutgoingUser, allowed_portal |
| |
| 4.1. "add_target" - if supported, this command MUST add new target with |
| name "target_name" and specified optional or required parameters. Each |
| parameter MUST be in form "parameter=value". All parameters MUST be |
| separated by ';' symbol. |
| |
| All target drivers supporting creation of virtual targets MUST support |
| this command. |
| |
| All target drivers supporting "add_target" command MUST support all |
| read-only targets' key attributes as parameters to "add_target" command |
| with the attributes' names as parameters' names and the attributes' |
| values as parameters' values. |
| |
| For example: |
| |
| echo "add_target TARGET1 parameter1=1; parameter2=2" >mgmt |
| |
| will add target with name "TARGET1" and parameters with names |
| "parameter1" and "parameter2" with values 1 and 2 correspondingly. |
| |
| 4.2. "del_target" - if supported, this command MUST delete target with |
| name "target_name". If "add_target" command is supported "del_target" |
| MUST also be supported. |
| |
| 4.3. "add_attribute" - if supported, this command MUST add a target |
| driver's attribute with the specified name and one or more values. |
| |
| All target drivers supporting run time creation of the target driver's |
| key attributes MUST support this command. |
| |
| For example, for iSCSI target: |
| |
| echo "add_attribute IncomingUser name password" >mgmt |
| |
| will add for discovery sessions an incoming user (attribute |
| /sys/kernel/scst_tgt/targets/iscsi/IncomingUser) with name "name" and |
| password "password". |
| |
| 4.4. "del_attribute" - if supported, this command MUST delete target |
| driver's attribute with the specified name and values. The values MUST |
| be specified, because in some cases attributes MAY internally be |
| distinguished by values. For instance, iSCSI target might have several |
| incoming users. If not needed, target driver might ignore the values. |
| |
| If "add_attribute" command is supported "del_attribute" MUST |
| also be supported. |
| |
| 4.5. "add_target_attribute" - if supported, this command MUST add new |
| attribute for the specified target with the specified name and one or |
| more values. |
| |
| All target drivers supporting run time creation of targets' key |
| attributes MUST support this command. |
| |
| For example: |
| |
| echo "add_target_attribute iqn.2006-10.net.vlnb:tgt IncomingUser name password" >mgmt |
| |
| will add for target with name "iqn.2006-10.net.vlnb:tgt" an incoming |
| user (attribute |
| /sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/IncomingUser) |
| with name "name" and password "password". |
| |
| 4.6. "del_target_attribute" - if supported, this command MUST delete |
| target's attribute with the specified name and values. The values MUST |
| be specified, because in some cases attributes MAY internally be |
| distinguished by values. For instance, iSCSI target might have several |
| incoming users. If not needed, target driver might ignore the values. |
| |
| If "add_target_attribute" command is supported "del_target_attribute" |
| MUST also be supported. |
| |
| Attributes for targets |
| ---------------------- |
| |
| Each target MAY support in its root subdirectory the following optional |
| attributes. Target drivers MAY also support there other read-only or |
| read-writable attributes. |
| |
| 1. "enabled" - this attribute MUST allow to enable and disable the |
| corresponding target, i.e. if disabled, the target MUST NOT accept new |
| connections. The goal of this attribute is to allow the target's initial |
| configuration. For instance, each target needs to have its LUNs setup |
| before it starts serving initiators. Another example is iSCSI target, |
| which may need to have initialized a number of iSCSI parameters before |
| it starts accepting new iSCSI connections. |
| |
| This attribute MUST have read and write permissions for superuser and be |
| read-only for other users. |
| |
| On read it MUST return 0, if the target is disabled, and 1, if it is |
| enabled. |
| |
| On write it MUST accept '0' character as request to disable and '1' as |
| request to enable. Other requests MUST be rejected. |
| |
| SCST core provides some facilities, which MUST be used to implement this |
| attribute. |
| |
| During disabling the target driver MAY close already connected sessions |
| to the target, but this is OPTIONAL. |
| |
| MUST be 0 by default. |
| |
| SCST core will automatically create for all targets the following |
| attribute: |
| |
| 1. "rel_tgt_id" - allows to read or write SCSI Relative Target Port |
| Identifier attribute. |
| |
| To provide OPTIONAL force close session functionality target drivers |
| MUST implement it using "force_close" write only session's attribute, |
| which on write to it MUST close the corresponding session. The |
| recommended way to implement it is to add close_session callback to the |
| target driver's struct scst_tgt_template. This way allows SCST on |
| initiators' security groups deletion to automatically force close |
| sessions in those groups. |
| |
| See SCST core's README for more info about those attributes. |
| |
| If a target driver supports both physical, i.e. hardware, and virtual |
| targets, as, for instance, NPIV Fibre Channel targets, to allow to |
| distinguish between them the physical targets MUST have "hw_target" |
| attribute, which MUST have value 1. The virtual targets MUST have |
| "parent_host" attribute, which MUST contain name of the parent hardware |
| target. Also, such target drivers MUST create virtual targets using |
| "add_target" command to mgmt attribute (see above), which MUST specify |
| the parent target for new virtual targets using "parent_host" attribute. |
| |
| |
| II. Rules for dev handlers |
| ========================== |
| |
| There are 2 types of dev handlers: parent dev handlers and children dev |
| handlers. The children dev handlers depend from the parent dev handlers. |
| |
| SCST core for each parent dev handler (struct scst_dev_type with |
| parent member with value NULL) creates a root subdirectory in |
| /sys/kernel/scst_tgt/handlers with name scst_dev_type.name (called |
| "dev_handler_name" further in this document). |
| |
| Parent dev handlers can have one or more subdirectories for children dev |
| handlers with names scst_dev_type.name of them. |
| |
| Only one level of the dev handlers' parent/children hierarchy is |
| allowed. Parent dev handlers, which support children dev handlers, MUST |
| NOT handle devices and MUST be only placeholders for the children dev |
| handlers. |
| |
| Further in this document children dev handlers or parent dev handlers, |
| which don't support children, will be called "end level dev handlers". |
| |
| End level dev handlers can be recognized by existence of the "mgmt" |
| attribute. |
| |
| For each device (struct scst_device) SCST core creates a root |
| subdirectory in /sys/kernel/scst_tgt/devices/device_name with name |
| scst_device.virt_name (called "device_name" further in this document). |
| |
| Attributes for dev handlers |
| --------------------------- |
| |
| Each dev handler MUST have it in its root subdirectory "mgmt" attribute, |
| which MUST support "add_device" and "del_device" attributes as described |
| below. |
| |
| Parent dev handlers and end level dev handlers without parents MAY |
| support in its root subdirectory the following optional attributes. They |
| MAY also support there other read-only or read-writable attributes. |
| |
| 1. "trace_level" - this attribute SHOULD allow to change log level of this |
| driver. |
| |
| This attribute SHOULD have read and write permissions for superuser and be |
| read-only for other users. |
| |
| On read it SHOULD return a help text about available command and log levels. |
| |
| On write it SHOULD accept commands to change log levels according to the |
| help text. |
| |
| For example: |
| |
| out_of_mem | minor | pid | line | function | special | mgmt | mgmt_dbg |
| |
| |
| Usage: |
| echo "all|none|default" >trace_level |
| echo "value DEC|0xHEX|0OCT" >trace_level |
| echo "add|del TOKEN" >trace_level |
| |
| where TOKEN is one of [debug, function, line, pid, |
| entryexit, buff, mem, sg, out_of_mem, |
| special, scsi, mgmt, minor, |
| mgmt_dbg, scsi_serializing, |
| retry, recv_bot, send_bot, recv_top, |
| send_top] |
| |
| 2. "version" - this read-only for all attribute SHOULD return version of |
| the dev handler and some info about its enabled compile time facilities. |
| |
| For example: |
| |
| 2.0.0 |
| EXTRACHECKS |
| DEBUG |
| |
| End level dev handlers in their root subdirectories MUST support "mgmt" |
| attribute and MAY support other read-only or read-writable attributes. |
| This attribute MUST have read and write permissions for superuser and be |
| read-only for other users. |
| |
| Attribute "mgmt" for virtual devices dev handlers |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| For virtual devices dev handlers "mgmt" attribute MUST allow to add and |
| delete devices as well as it MAY allow to add and delete the dev |
| handler's or its devices' attributes. |
| |
| On read it MUST return a help string describing available commands and |
| parameters. |
| |
| To achieve that the dev handler should just set in its struct |
| scst_dev_type correctly the following fields: mgmt_cmd_help, |
| add_device_parameters, devt_optional_attributes and |
| dev_optional_attributes. |
| |
| For example: |
| |
| Usage: echo "add_device device_name [parameters]" >mgmt |
| echo "del_device device_name" >mgmt |
| echo "add_attribute <attribute> <value>" >mgmt |
| echo "del_attribute <attribute> <value>" >mgmt |
| echo "add_device_attribute device_name <attribute> <value>" >mgmt |
| echo "del_device_attribute device_name <attribute> <value>" >mgmt |
| |
| where parameters are one or more param_name=value pairs separated by ';' |
| |
| The following parameters available: filename, blocksize, write_through, nv_cache, o_direct, read_only, removable |
| The following device driver attributes available: AttributeX, AttributeY |
| The following device attributes available: AttributeDX, AttributeDY |
| |
| 1. "add_device" - this command MUST add new device with name |
| "device_name" and specified optional or required parameters. Each |
| parameter MUST be in form "parameter=value". All parameters MUST be |
| separated by ';' symbol. |
| |
| All dev handlers supporting "add_device" command MUST support all |
| read-only devices' key attributes as parameters to "add_device" command |
| with the attributes' names as parameters' names and the attributes' |
| values as parameters' values. |
| |
| For example: |
| |
| echo "add_device device1 parameter1=1; parameter2=2" >mgmt |
| |
| will add device with name "device1" and parameters with names |
| "parameter1" and "parameter2" with values 1 and 2 correspondingly. |
| |
| 2. "del_device" - this command MUST delete device with name |
| "device_name". |
| |
| 3. "add_attribute" - if supported, this command MUST add a device |
| driver's attribute with the specified name and one or more values. |
| |
| All dev handlers supporting run time creation of the dev handler's |
| key attributes MUST support this command. |
| |
| For example: |
| |
| echo "add_attribute AttributeX ValueX" >mgmt |
| |
| will add attribute |
| /sys/kernel/scst_tgt/handlers/dev_handler_name/AttributeX with value ValueX. |
| |
| 4. "del_attribute" - if supported, this command MUST delete device |
| driver's attribute with the specified name and values. The values MUST |
| be specified, because in some cases attributes MAY internally be |
| distinguished by values. If not needed, dev handler might ignore the |
| values. |
| |
| If "add_attribute" command is supported "del_attribute" MUST also be |
| supported. |
| |
| 5. "add_device_attribute" - if supported, this command MUST add new |
| attribute for the specified device with the specified name and one or |
| more values. |
| |
| All dev handlers supporting run time creation of devices' key attributes |
| MUST support this command. |
| |
| For example: |
| |
| echo "add_device_attribute device1 AttributeDX ValueDX" >mgmt |
| |
| will add for device with name "device1" attribute |
| /sys/kernel/scst_tgt/devices/device_name/AttributeDX) with value |
| ValueDX. |
| |
| 6. "del_device_attribute" - if supported, this command MUST delete |
| device's attribute with the specified name and values. The values MUST |
| be specified, because in some cases attributes MAY internally be |
| distinguished by values. If not needed, dev handler might ignore the |
| values. |
| |
| If "add_device_attribute" command is supported "del_device_attribute" |
| MUST also be supported. |
| |
| Attribute "mgmt" for pass-through devices dev handlers |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| For pass-through devices dev handlers "mgmt" attribute MUST allow to |
| assign and unassign this dev handler to existing SCSI devices via |
| "add_device" and "del_device" commands correspondingly. |
| |
| On read it MUST return a help string describing available commands and |
| parameters. |
| |
| For example: |
| |
| Usage: echo "add_device H:C:I:L" >mgmt |
| echo "del_device H:C:I:L" >mgmt |
| |
| 1. "add_device" - this command MUST assign SCSI device with |
| host:channel:id:lun numbers to this dev handler. |
| |
| All pass-through dev handlers MUST support this command. |
| |
| For example: |
| |
| echo "add_device 1:0:0:0" >mgmt |
| |
| will assign SCSI device 1:0:0:0 to this dev handler. |
| |
| 2. "del_device" - this command MUST unassign SCSI device with |
| host:channel:id:lun numbers from this dev handler. |
| |
| SCST core will automatically create for all dev handlers the following |
| attributes: |
| |
| 1. "type" - SCSI type of device this dev handler can handle. |
| |
| See SCST core's README for more info about those attributes. |
| |
| Attributes for devices |
| ---------------------- |
| |
| Each device MAY support in its root subdirectory any read-only or |
| read-writable attributes. |
| |
| SCST core will automatically create for all devices the following |
| attributes: |
| |
| 1. "type" - SCSI type of this device |
| |
| See SCST core's README for more info about those attributes. |
| |
| |
| III. Rules for management utilities |
| =================================== |
| |
| Rules summary |
| ------------- |
| |
| A management utility (scstadmin) SHOULD NOT keep any knowledge specific |
| to any device, dev handler, target or target driver. It SHOULD only know |
| the common SCST SYSFS rules, which all dev handlers and target drivers |
| MUST follow. Namely: |
| |
| Common rules: |
| ~~~~~~~~~~~~~ |
| |
| 1. All key attributes MUST be marked by mark "[key]" in the last line of |
| the attribute. |
| |
| 2. All not key attributes don't matter and SHOULD be ignored. |
| |
| For target drivers and targets: |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| 1. If target driver supports adding new targets, it MUST have "mgmt" |
| attribute, which MUST support "add_target" and "del_target" commands as |
| specified above. |
| |
| 2. If target driver supports run time adding new key attributes, it MUST |
| have "mgmt" attribute, which MUST support "add_attribute" and |
| "del_attribute" commands as specified above. |
| |
| 3. If target driver supports both hardware and virtual targets, all its |
| hardware targets MUST have "hw_target" attribute with value 1. |
| |
| 4. If target has read-only key attributes, the add_target command MUST |
| support them as parameters. |
| |
| 5. If target supports run time adding new key attributes, the target |
| driver MUST have "mgmt" attribute, which MUST support |
| "add_target_attribute" and "del_target_attribute" commands as specified |
| above. |
| |
| 6. Both target drivers and targets MAY support "enable" attribute. If |
| supported, after configuring the corresponding target driver or target |
| "1" MUST be written to this attribute in the following order: at first, |
| for all targets of the target driver, then for the target driver. |
| |
| For devices and dev handlers: |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| 1. Each dev handler in its root subdirectory MUST have "mgmt" attribute. |
| |
| 2. Each dev handler MUST support "add_device" and "del_device" commands |
| to the "mgmt" attribute as specified above. |
| |
| 3. If dev handler driver supports run time adding new key attributes, it |
| MUST support "add_attribute" and "del_attribute" commands to the "mgmt" |
| attribute as specified above. |
| |
| 4. All device handlers have links in the root subdirectory pointing to |
| their devices. |
| |
| 5. If device has read-only key attributes, the "add_device" command MUST |
| support them as parameters. |
| |
| 6. If device supports run time adding new key attributes, its dev |
| handler MUST support "add_device_attribute" and "del_device_attribute" |
| commands to the "mgmt" attribute as specified above. |
| |
| 7. Each device has "handler" link to its dev handler's root |
| subdirectory. |
| |
| How to distinguish and process different types of attributes |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| Since management utilities only interested in key attributes, they |
| should simply ignore all non-key attributes, like |
| devices/device_name/type or targets/target_driver/target_name/version |
| doesn't matter if they are read-only or writable. So, the word "key" |
| will be omitted later in this section. |
| |
| At first, any attribute can be a key attribute, doesn't matter how it's |
| created. |
| |
| All the existing on the configuration save time attributes should be |
| treated the same. Management utilities shouldn't try to separate anyhow |
| them in config files. |
| |
| 1. Always existing attributes |
| ----------------------------- |
| |
| There are 2 type of them: |
| |
| 1.1. Writable, like devices/device_name/t10_dev_id or |
| targets/qla2x00tgt/target_name/explicit_confirmation. They are the |
| simplest and all the values can just be read and written from/to them. |
| |
| On the configuration save time they can be distinguished as existing. |
| |
| On the write configuration time they can be distinguished as existing |
| and writable. |
| |
| 1.2. Read-only, like devices/fileio_device_name/filename or |
| devices/fileio_device_name/block_size. They are also easy to distinguish |
| looking at the permissions. |
| |
| On the configuration save time they can be distinguished the same as for |
| (1.1) as existing. |
| |
| On the write configuration time they can be distinguished as existing |
| and read-only. They all should be passed to "add_target" or |
| "add_device" commands for virtual targets and devices correspondingly. |
| To apply changes to them, the whole corresponding object |
| (fileio_device_name in this example) should be removed then recreated. |
| |
| 2. Optional |
| ----------- |
| |
| For instance, targets/iscsi/IncomingUser or |
| targets/iscsi/target_name/IncomingUser. There are 4 types of them: |
| |
| 2.1. Global for target drivers and dev handlers |
| ----------------------------------------------- |
| |
| For instance, targets/iscsi/IncomingUser or handlers/vdisk_fileio/XX |
| (none at the moment). |
| |
| On the configuration save time they can be distinguished the same as for |
| (1.1). |
| |
| On the write configuration time they can be distinguished as one of 4 |
| choices: |
| |
| 2.1.1. Existing and writable. In this case they should be treated as |
| (1.1) |
| |
| 2.1.2. Existing and read-only. In this case they should be treated as |
| (1.2). |
| |
| 2.1.3. Not existing. In this case they should be added using |
| "add_attribute" command. |
| |
| 2.1.4. Existing in the sysfs tree and not existing in the config file. |
| In this case they should be deleted using "del_attribute" command. |
| |
| 2.2. Global for targets |
| ----------------------- |
| |
| For instance, targets/iscsi/target_name/IncomingUser. |
| |
| On the configuration save time they can be distinguished the same as (1.1). |
| |
| On the write configuration time they can be distinguished as one of 4 |
| choices: |
| |
| 2.2.1. Existing and writable. In this case they should be treated as |
| (1.1). |
| |
| 2.2.2. Existing and read-only. In this case they should be treated as |
| (1.2). |
| |
| 2.2.3. Not existing. In this case they should be added using |
| "add_target_attribute" command. |
| |
| 2.2.4. Existing in the sysfs tree and not existing in the config file. |
| In this case they should be deleted using "del_target_attribute" |
| command. |
| |
| 2.3. Global for devices |
| ----------------------- |
| |
| For instance, devices/nullio/t10_dev_id. |
| |
| On the configuration save time they can be distinguished the same as (1.1). |
| |
| On the write configuration time they can be distinguished as one of 4 |
| choices: |
| |
| 2.3.1. Existing and writable. In this case they should be treated as |
| (1.1) |
| |
| 2.3.2. Existing and read-only. In this case they should be treated as |
| (1.2). |
| |
| 2.3.3. Not existing. In this case they should be added using |
| "add_device_attribute" command for the corresponding handler, e.g. |
| devices/nullio/handler/. |
| |
| 2.3.4. Existing in the sysfs tree and not existing in the config file. |
| In this case they should be deleted using "del_device_attribute" |
| command for the corresponding handler, e.g. devices/nullio/handler/. |
| |
| Thus, management utility should implement only 8 procedures: (1.1), |
| (1.2), (2.1.3), (2.1.4), (2.2.3), (2.2.4), (2.3.3), (2.3.4). |
| |
| |
| How to distinguish hardware and virtual targets |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| A target is hardware: |
| |
| * if exist both "hw_target" attribute and "mgmt" management file |
| |
| * or if both don't exist |
| |
| A target is virtual if there is "mgmt" file and "hw_target" attribute |
| doesn't exist. |
| |
| |
| Algorithm to convert current SCST configuration to config file |
| -------------------------------------------------------------- |
| |
| A management utility SHOULD use the following algorithm when converting |
| current SCST configuration to a config file. |
| |
| For all attributes with digits at the end the name, the digits part |
| should be omitted from the attributes' names during the store. For |
| instance, "IncomingUser1" should be stored as "IncomingUser". |
| |
| 1. Scan all attributes in /sys/kernel/scst_tgt (not recursive) and store |
| all found key attributes. |
| |
| 2. Scan all subdirectories of /sys/kernel/scst_tgt/handlers. Each |
| subdirectory with "mgmt" attribute is a root subdirectory of a dev |
| handler with name the name of the subdirectory. For each found dev |
| handler do the following: |
| |
| 2.1. Store the dev handler's name. Store also its path to the root |
| subdirectory, if it isn't default (/sys/kernel/scst_tgt/handlers/handler_name). |
| |
| 2.2. Store all dev handler's key attributes. |
| |
| 2.3. Go through all links in the root subdirectory pointing to |
| /sys/kernel/scst_tgt/devices and for each device: |
| |
| 2.3.1. For virtual devices dev handlers: |
| |
| 2.3.1.1. Store the name of the device. |
| |
| 2.3.1.2. Store all key attributes. Mark all read only key attributes |
| during storing, they will be parameters for the device's creation. |
| |
| 2.3.2. For pass-through devices dev handlers: |
| |
| 2.3.2.1. Store the H:C:I:L name of the device. Optionally, instead of |
| the name unique T10 vendor device ID found using command: |
| |
| sg_inq -p 0x83 /dev/sdX |
| |
| can be stored. It will allow to reliably find out this device if on the |
| next reboot it will have another host:channel:id:lin numbers. The sdX |
| device can be found as the last letters after ':' in |
| /sys/kernel/scst_tgt/devices/H:C:I:L/scsi_device/device/block:sdX. |
| |
| 3. Go through all subdirectories in /sys/kernel/scst_tgt/targets. For |
| each target driver: |
| |
| 3.1. Store the name of the target driver. |
| |
| 3.2. Store all its key attributes. |
| |
| 3.3. Go through all target's subdirectories. For each target: |
| |
| 3.3.1. Store the name of the target. |
| |
| 3.3.2. Mark if the target is hardware or virtual target. The target is a |
| hardware target if it has "hw_target" attribute or its target driver |
| doesn't have "mgmt" attribute. |
| |
| 3.3.3. Store all key attributes. Mark all read only key attributes |
| during storing, they will be parameters for the target's creation. |
| |
| 3.3.4. Scan all "luns" subdirectory and store: |
| |
| - LUN. |
| |
| - LU's device name. |
| |
| - Key attributes. |
| |
| 3.3.5. Scan all "ini_groups" subdirectories. For each group store the following: |
| |
| - The group's name. |
| |
| - The group's LUNs (the same info as for 3.3.4). |
| |
| - The group's initiators. |
| |
| 3.3.6. Store value of "enabled" attribute, if it exists. |
| |
| 3.4. Store value of "enabled" attribute, if it exists. |
| |
| |
| Algorithm to initialize SCST from config file |
| --------------------------------------------- |
| |
| A management utility SHOULD use the following algorithm when doing |
| initial SCST configuration from a config file. All necessary kernel |
| modules and user space programs supposed to be already loaded, hence all |
| dev handlers' entries in /sys/kernel/scst_tgt/handlers as well as all |
| entries for hardware targets already created. |
| |
| 1. Set stored values for all stored global (/sys/kernel/scst_tgt) |
| attributes. |
| |
| 2. For each dev driver: |
| |
| 2.1. Set stored values for all already existing stored attributes. |
| |
| 2.2. Create not existing stored attributes using "add_attribute" command. |
| |
| 2.3. For virtual devices dev handlers for each stored device: |
| |
| 2.3.1. Create the device using "add_device" command using marked read |
| only attributes as parameters. |
| |
| 2.3.2. Set stored values for all already existing stored attributes. |
| |
| 2.3.3. Create not existing stored attributes using |
| "add_device_attribute" command. |
| |
| 2.4. For pass-through dev handlers for each stores device: |
| |
| 2.4.1. Assign the corresponding pass-through device to this dev handler |
| using "add_device" command. |
| |
| 3. For each target driver: |
| |
| 3.1. Set stored values for all already existing stored attributes. |
| |
| 3.2. Create not existing stored attributes using "add_attribute" command. |
| |
| 3.3. For each target: |
| |
| 3.3.1. For virtual targets: |
| |
| 3.3.1.1. Create the target using "add_target" command using marked read |
| only attributes as parameters. |
| |
| 3.3.1.2. Set stored values for all already existing stored attributes. |
| |
| 3.3.1.3. Create not existing stored attributes using |
| "add_target_attribute" command. |
| |
| 3.3.2. For hardware targets for each target: |
| |
| 3.3.2.1. Set stored values for all already existing stored attributes. |
| |
| 3.3.2.2. Create not existing stored attributes using |
| "add_target_attribute" command. |
| |
| 3.3.3. Setup LUNs |
| |
| 3.3.4. Setup ini_groups, their LUNs and initiators' names. |
| |
| 3.3.5. If this target supports enabling, enable it. |
| |
| 3.4. If this target driver supports enabling, enable it. |
| |
| |
| Algorithm to apply changes in config file to currently running SCST |
| ------------------------------------------------------------------- |
| |
| A management utility SHOULD use the following algorithm when applying |
| changes in config file to currently running SCST. |
| |
| Not all changes can be applied on enabled targets or enabled target |
| drivers. From other side, for some target drivers enabling/disabling is |
| a very long and disruptive operation, which should be performed as rare |
| as possible. Thus, the management utility SHOULD support additional |
| option, which, if set, will make it to disable all affected targets |
| before doing any change with them. |
| |
| 1. Scan all attributes in /sys/kernel/scst_tgt (not recursive) and |
| compare stored and actual key attributes. Apply all changes. |
| |
| 2. Scan all subdirectories of /sys/kernel/scst_tgt/handlers. Each |
| subdirectory with "mgmt" attribute is a root subdirectory of a dev |
| handler with name the name of the subdirectory. For each found dev |
| handler do the following: |
| |
| 2.1. Compare stored and actual key attributes. Apply all changes. Create |
| new attributes using "add_attribute" commands and delete not needed any |
| more attributes using "del_attribute" command. |
| |
| 2.2. Compare existing devices (links in the root subdirectory pointing |
| to /sys/kernel/scst_tgt/devices) and stored devices in the config file. |
| Delete all not needed devices and create new devices. |
| |
| 2.3. For all existing devices: |
| |
| 2.3.1. Compare stored and actual key attributes. Apply all changes. |
| Create new attributes using "add_device_attribute" commands and delete |
| not needed any more attributes using "del_device_attribute" command. |
| |
| 2.3.2. If any read only key attribute for virtual device should be |
| changed, delete the devices and recreate it. |
| |
| 3. Go through all subdirectories in /sys/kernel/scst_tgt/targets. For |
| each target driver: |
| |
| 3.1. If this target driver should be disabled, disable it. |
| |
| 3.2. Compare stored and actual key attributes. Apply all changes. Create |
| new attributes using "add_attribute" commands and delete not needed any |
| more attributes using "del_attribute" command. |
| |
| 3.3. Go through all target's subdirectories. Compare existing and stored |
| targets. Delete all not needed targets and create new targets. |
| |
| 3.4. For all existing targets: |
| |
| 3.4.1. If this target should be disabled, disable it. |
| |
| 3.4.2. Compare stored and actual key attributes. Apply all changes. |
| Create new attributes using "add_target_attribute" commands and delete |
| not needed any more attributes using "del_target_attribute" command. |
| |
| 3.4.3. If any read only key attribute for virtual target should be |
| changed, delete the target and recreate it. |
| |
| 3.4.4. Scan all "luns" subdirectory and apply necessary changes, using |
| "replace" commands to replace one LUN by another, if needed. |
| |
| 3.4.5. Scan all "ini_groups" subdirectories and apply necessary changes, |
| using "replace" commands to replace one LUN by another and "move" |
| command to move initiator from one group to another, if needed. It MUST |
| be done in the following order: |
| |
| - Necessary initiators deleted, if they aren't going to be moved |
| |
| - LUNs updated |
| |
| - Necessary initiators added or moved |
| |
| 3.4.6. If this target should be enabled, enable it. |
| |
| 3.5. If this target driver should be enabled, enable it. |
| |