NAME

       saveconfig.json - Saved configuration file for rtslib-fb and LIO kernel target

DESCRIPTION

       /etc/rtslib-fb-target/saveconfig.json  is the default location for storing the configuration of the Linux
       kernel target, also known as LIO. Since the target is in the kernel, tools like  targetctl  or  targetcli
       must be used to save and restore the configuration across reboots.

       Generating  or  modifying this file by hand, or with other tools, is also supported. This fills a gap for
       users whose needs are not met by the targetcli configuration shell, who  cannot  use  the  rtslib  Python
       library, and yet also wish to avoid directly manipulating LIO's configfs interface.

OVERVIEW

       The  configuration  file  is  in  the  "json" text format, which is both human- and machine-readable. Its
       format is very closely modeled on the layout and terminology that LIO uses.  Attributes  may  be  string,
       boolean, or numeric values. All sizes are expressed in bytes.

LAYOUT

   TOP LEVEL SUMMARY
       storage_objects  describes  mappings  of resources on the local machine that can be used to emulate block
       devices.

       fabric_modules describes settings for LIO fabrics -- the hardware or software  protocols  that  transport
       SCSI commands -- such as iSCSI or Fibre Channel over Ethernet (FCoE).

       targets describes the SCSI target endpoints that export storage objects over a fabric.

   storage_objects
       All storage objects must contain name and plugin values. Each name must be unique for all storage objects
       of its plugin type.

       plugin must be one of: fileio, block, pscsi, or ramdisk.

       Objects  with  plugin  value  of fileio must also contain dev, which is the full path to the file that is
       backing the storage object.  Optional fileio attributes are wwn (string), write_back (boolean), and  size
       (number).  If the file given in dev does not exist, then size must be present, and a backing file of that
       size will be created.

       Objects with plugin value of block must also contain dev, which is the full path to the block device that
       is  backing  the  storage  object.  Optional block attributes are wwn (string), write_back (boolean), and
       readonly (boolean).

       Objects with plugin value of pscsi must also contain dev, which is the full path to the SCSI device  that
       is backing the storage object.  There are no optional attributes.

       Objects  with  plugin value of ramdisk must also contain size (number), which is the size in bytes of the
       ramdisk.  Optional ramdisk attributes are wwn (string), and nullio (boolean).

       All storage object definitions may also contain an attributes object. This contains LIO attribute values,
       all of which are also optional. Please see LIO documentation for more information on these.

   fabric_modules
       This section is limited to  setting  discovery  authentication  settings  for  fabrics  that  support  it
       (currently just iscsi). Objects here should contain name (e.g. "iscsi"), userid, password, mutual_userid,
       and mutual_password string values.

   targets
       Target configuration is modeled on iSCSI, in which a named target can contain multiple sub-configurations
       called  Target  Port  Groups (TPGs). LIO follows this model for describing configuration even for fabrics
       that do not support TPGs.

       Objects in targets contain just three attributes: wwn is the world-wide name the target has  been  given.
       This may start with "iqn", or "naa", for example.  fabric is the name of the fabric module this target is
       exported  over. Allowed values for this depend on the system configuration, but examples include "iscsi",
       "loopback", and "tcm_fc".  tpgs is a list of objects describing 1 or more TPGs, described below.

   tpgs
       TPG object attributes are all optional. Values not supplied will be set to default values.  tag  (number)
       allows  the  tpg  tag  to  be specified.  enable (bool, default to true) allows the TPG to be disabled or
       enabled.  luns, portals, and node_acls contain  further  lists  of  objects,  descibed  below.   Finally,
       userid, password, mutual_userid, and mutual_password allow main-phase authentication values to be set for
       fabrics  (like  iSCSI) that support TPG-level authentication. (Please see targetcli(8) for details on TPG
       versus ACL-based authentication.) Finally, TPGs can  also  contain  optional  attributes  and  parameters
       lists, see LIO documentation for more information.

   luns
       This  list  of objects maps storage objects to the TPG.  index is a TPG-unique number for the assignment,
       which may be used as the LU number for fabrics that do not support ACL  mappings.   storage_object  is  a
       string  linking back to a storage object, of the format "/backstores/<plugin>/<name>", where <plugin> and
       <name> correspond to a storage object defined under storage_objects.

   portals
       Portals describe connection endpoints for iSCSI targets. Required values are ip_address (string) and port
       (number).  iser (boolean) is an optional value to enable iSER.  offload (boolean) is an optional value to
       enable hardware offload.

   node_acls
       This contains information about explicit initiator LUN mappings.   node_wwn  (string)  must  be  present.
       Authentication   may  also  be  set  on  a  per-ACL  basis  with  userid,  password,  mutual_userid,  and
       mutual_password, similar to TPGs.  mapped_luns is a list  of  mapped  luns,  described  below.   Finally,
       node_acls can contain an optional attributes list.

   mapped_luns
       Objects in mapped_luns contain three required attributes.  write_protect (boolean) sets the write-protect
       status  of  the  mapped  LUN.   tpg_lun (number) corresponds to an existing entry in the TPG's luns list.
       index is the LU number that the mapped LUN will claim.

EXAMPLE CONFIGURATION

       Since tools generate this file, one good way to understand its format is to use a tool like targetcli  to
       configure a target, then run saveconfig, and view the resulting json file.

SEE ALSO

       targetcli(8), targetctl(8)

FILES

       /etc/rtslib-fb-target/saveconfig.json

AUTHOR

       Man page written by Andy Grover <agrover@redhat.com>.

REPORTING BUGS

       Report bugs via <targetcli-fb-devel@lists.fedorahosted.org>
       or <https://github.com/open-iscsi/rtslib-fb/issues>

                                                                                              saveconfig.json(5)