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)