Provided by: ceph-iscsi_3.6-3_all bug

NAME

       gwcli - manage iscsi gateway configuration from the command line

DESCRIPTION

       gwcli  is  a  configuration  shell  interface  used  for  viewing,  editing and saving the
       configuration of a ceph/iSCSI gateway environment. It enables the administrator to  define
       rbd  devices, map them across gateway nodes and export them to various clients over iSCSI.
       In addition to managing the  iSCSI  related  elements  of  the  configuration,  the  shell
       provides  an overview of the ceph cluster, describing the available pools and the capacity
       they provide. Since rbd  images  are  thin  provisioned,  the  capacity  information  also
       indicates  the capacity over-commit of the pools, enabling the admin to make more informed
       choices when allocating new rbd images.

       iSCSI services are implemented by the kernel's LIO  target  subsystem  layer,  with  iSCSI
       settings  enforced by the rbd-target-gw daemon. The targetcli command may still be used to
       view lower level detail of the LIO environment, but all changes must  be  made  using  the
       gwcli.

       The gwcli shell is similar to the targetcli interface, and is also based on 'configshell'.
       The layout of the UI is a tree format, and  is  navigated  in  much  the  same  way  as  a
       filesystem.

USAGE

       gwcli [-d | --debug]

       The -d option provides additional verbosity within the shell

       gwcli [cmd]

       Invoke  gwcli  as  root  to  enter  the  interactive shell, or supply a command to execute
       without entering the shell. Within the shell, us ls to  list  nodes  beneath  the  current
       path.  Moving  around  the  tree  is  done using the cd command, or by simply entering the
       'path' of the new location/node directly. Use help <cmd> for  specific  help  information.
       The shell provides tab completion for commands and command arguments.

       Configuration  state  is  persisted  within a rados object stored in the 'rbd' pool. gwcli
       orchestrates changes across all iscsi gateways via the rbd-target-api service  running  on
       each  gateway.  Once  the  change  to  the  local LIO subsystem is complete, the change is
       committed to the rados configuration object. Although 'targetcli'  is  available,  it  can
       only really provide a view of the local LIO configuration.

QUICKSTART

       gwcli  interacts  with  an  API  service  provided  by each iSCSI gateway's rbd-target-api
       daemon. The API service is installed with the cli, and can be configured by  updating  the
       api_* related settings in '/etc/ceph/iscsi-gateway.cfg'.

       Typically, the following options are regarded as site specific;

          api_user = <user_name>
          api_password = <password>
          api_port = <port_number>
          api_secure = <true or false>

       NB. An example iscsi-gateway.cfg file is provided under /usr/share/doc/ceph-iscsi-config*

       Access  to  the  API  is normally restricted to the IP's of the gateway nodes, but you may
       also define other IP addresses that should be granted access to  the  API  by  adding  the
       following entry to the configuration file;

          trusted_ip_list = <ip_address,ip_address...>

       By  default  the  API  service  is  not running with TLS, so for a more secure environment
       ensure iscsi-gateway.cfg has "api_secure = true" defined. When using secure mode you  will
       need  to  create  the  appropriate  certificate  and  private key files, and place them in
       /etc/ceph as 'iscsi-gateway.crt' and 'iscsi-gateway.key' on each gateway node.

       Once these files are inplace across the nodes, the rbd-target-api service can be  started.
       Check  that the API service is enabled and in the correct mode by looking at the output of
       'systemctl status rbd-target-api'. You should see a message similar to

          * Running on https://0.0.0.0:5000/.

       The example gwcli output below shows a small two-gateway configuration, supporting 2 iSCSI
       clients

       $ sudo gwcli

       /> ls
       /> ls
       o- / ................................................................... [...]
         o- clusters .................................................. [Clusters: 1]
         | o- ceph ...................................................... [HEALTH_OK]
         |   o- pools .................................................... [Pools: 3]
         |   | o- ec ......................... [(2+1), Commit: 0b/40G (0%), Used: 0b]
         |   | o- iscsi ...................... [(x3), Commit: 0b/20G (0%), Used: 18b]
         |   | o- rbd ........................ [(x3), Commit: 8G/20G (40%), Used: 5K]
         |   o- topology .......................................... [OSDs: 3,MONs: 3]
         o- disks .................................................... [8G, Disks: 5]
         | o- rbd ........................................................ [rbd (8G)]
         |   o- disk_1 ............................................ [rbd/disk_1 (1G)]
         |   o- disk_2 ............................................ [rbd/disk_2 (2G)]
         |   o- disk_3 ............................................ [rbd/disk_3 (2G)]
         |   o- disk_4 ............................................ [rbd/disk_4 (1G)]
         |   o- disk_5 ............................................ [rbd/disk_5 (2G)]
         o- iscsi-targets .............................................. [Targets: 1]
           o- iqn.2003-01.com.redhat.iscsi-gw:ceph-gw ................. [Gateways: 2]
             o- disks .................................................... [Disks: 5]
             | o- rbd/disk_1 ....................................... [Owner: rh7-gw1]
             | o- rbd/disk_5 ....................................... [Owner: rh7-gw2]
             o- gateways ...................................... [Up: 2/2, Portals: 2]
             | o- rh7-gw1 ..................................... [192.168.122.69 (UP)]
             | o- rh7-gw2 .................................... [192.168.122.104 (UP)]
             o- host-groups ............................................ [Groups : 1]
             | o- group1 ....................................... [Hosts: 1, Disks: 1]
             |   o- iqn.1994-05.com.redhat:rh7-client ........................ [host]
             |   o- rbd/disk_5 ............................................... [disk]
             o- hosts .................................................... [Hosts: 2]
               o- iqn.1994-05.com.redhat:myhost1 ......... [Auth: None, Disks: 1(1G)]
               | o- lun 0 .......................... [rbd/disk_1(1G), Owner: rh7-gw2]]
               o- iqn.1994-05.com.redhat:rh7-client  [LOGGED-IN, Auth: CHAP, Disks: 1(2G)]
                 o- lun 0 .......................... [rbd/disk_5(2G), Owner: rh7-gw2]]

       Disks  exported  through  the  gateways use ALUA attributes to provide ActiveOptimised and
       ActiveNonOptimised access to the rbd images. Each disk is  assigned  a  primary  owner  at
       creation/import time - shown above with the owner attribute.

DISKS

       In  order  to  manage rbd images (disks) within the environment there are several commands
       that enable you to create, resize and delete rbd's from the  ceph  cluster.  When  an  rbd
       image  is  created,  it is registered with all gateways. Part of this registration process
       defines the gateway that will provide the active I/O path to the LUN  (disk)  for  any/all
       clients. This means that the iscsi-target definition and the gateway hosts must be defined
       prior to any disks being created (added to the gateways). It's also important to note that
       for  an rbd image to be compatible with the iSCSI environment, it must have specific image
       features enabled (exclusive_lock, layering). The easiest way to create new disks is  using
       the /disks create command.

       /disks/ create pool=<pool> image=<image_name> size=<N>G
              Using  the  create command ensure the image features are applied correctly. You can
              also choose to create your rbd images by  some  other  means,  in  which  case  the
              'create'  command  will effectively 'import' the rbd into the configuration leaving
              any data already on the device, intact.

       /disks/<disk_name>/ resize <N>g
       /disks resize <disk_name> <new_size>
              Use the resize command to increase the capacity of a specific rbd image.

       /disks/ delete <disk_name>
              The delete command allows you to remove the rbd from  the  LIO  and  ceph  cluster.
              Prior  to  the delete being actioned the current configuration is checked to ensure
              that the requested rbd image is not masked to any iSCSI client. Once this check  is
              successful,  the  rbd image will be purged from the LIO environment on each gateway
              and deleted from the ceph cluster.

ISCSI-TARGETS

       The iscsi-target provides the end-point name that clients will know  the  iSCSI  'cluster'
       as.  The target IQN will be created across all gateways within the configuration. Once the
       target is defined, the iscsi-target sub-tree is populated with entries  for  gateways  and
       hosts.

       /iscsi-targets/ create <valid_IQN>
              The  IQN provided will be validated and defined to the configuration object. Adding
              gateway nodes will then pick up the configuration's IQN and apply it to their local
              LIO instance.

       /iscsi-targets/ clearconfig confirm=true
              The  clearconfig  command  provides  the  ability to return each of the gateways to
              their undefined state. However, since this is a disruptive command you must  remove
              the clients and disks first, before issuing a clearconfig.

GATEWAYS

       Gateways provide the access points for rbd images over iSCSI, so there should be a minimum
       of 2 defined to provide fault tolerance.

       /iscsi-targets/<iqn>/ create <node_name> <portal_ip_address>
              Gateways are defined by a node name (preferably a shortname, but it must  resolve),
              and  an IPv4/IPv6 address that the iSCSI 'service' will be bound to (i.e. the iSCSI
              portal IP address). When adding a gateway, the candidate machine will be checked to
              ensure the relevant files and daemons are in place.

HOST-GROUPS

       Host groups provide a more convenient way of managing multiple servers that must share the
       same disk masking configuration. For example in a RHV/oVirt or  Vmware  environment,  each
       host  needs access to the same LUNs. Host groups allow you to create a logical group which
       contains the hosts and the disks that each host in the group should have access to. Please
       note  that  sharing  devices  across  hosts needs a cluster aware filesystem or equivalent
       locking to avoid data corruption.

       /iscsi-targets/<iqn>/host-groups/ create | delete <group-name>
              Create or delete a given group name. Deleting a group definition  does  not  remove
              the  hosts  or  LUN  masking,  it  simply  removes  the  logical  grouping used for
              management purposes.

       /iscsi-targets/<iqn>/host-groups/<group_name>/ host add | remove <client-iqn>
              The host subcommand within a group definition allows you to add  and  remove  hosts
              from  the group. When adding a host, it must not have existing LUN masking in place
              - this restriction ensure lun id consistency  across  all  hosts  within  the  host
              group. Removing a host from a group does not automatically remove it's LUN masking.

       /iscsi-targets/<iqn>/host-groups/<group_name>/ disk add | remove <pool>.<image_name>
              The  disk subcommand enables you to add and remove disks to/from all members of the
              host group.

              NB.Once a client is a member of a host group, it's disks can only be managed at the
              group level.

HOSTS

       The 'hosts' section defines the iSCSI client definitions (NodeACLs) that provide access to
       the rbd images. The CLI provides the ability to create and delete  clients,  define/update
       chap authentication and add and remove rbd images for the client.

       /iscsi-targets/<iqn>/hosts/ create <client_iqn>
              The  create  command  will  define  the  client  IQN  to  all  gateways  within the
              configuration. At creation time, the client IQN is  added  to  a  ACL  that  allows
              normal  iSCSI  session  logins  for  all  clients  with  the  IQN.  To  enable CHAP
              authentication use the auth command described below.

       /iscsi-targets/<iqn>/hosts/ delete <client_iqn>
              The delete command will attempt to remove client IQN from all gateways  within  the
              configuration.  The  client  must  be  logged  out,  for  the  delete command to be
              successful.

       /iscsi-targets/<iqn>/hosts/ auth nochap
              CHAP authentication can be reset to initiator based ACLs target wide for all  setup
              ACLs  using the nochap keyword. If there are multiple clients, CHAP must be enabled
              for all clients or disabled for all clients. gwcli does  not  support  mixing  CHAP
              clients with IQN ACL clients.

       /iscsi-targets/<iqn>/hosts/<client_iqn>/ auth chap=<user>/<pswd>
              CHAP  authentication  can  be  defined for the client with the chap= parameter. The
              username and password defined here must then  be  used  within  the  clients  login
              credentials  for  this  iscsi  target.  If there are multiple clients, CHAP must be
              enabled for all clients or disabled for all clients. gwcli does not support  mixing
              CHAP clients with IQN ACL clients.

       /iscsi-targets/<iqn>/hosts/<client_iqn>/ disk add | remove <disk_name>
              rbd  images  defined  to the iscsi gateway, become LUNs within the LIO environment.
              These LUNs can be masked to,  or  masked  from  specific  clients  using  the  disk
              command.  When  a  disk is masked to a client, the disk is automatically assigned a
              LUN id. The disk->LUN id relationship  is  persisted  in  the  rados  configuration
              object  to ensure that the disk always appears on the clients SCSI interface at the
              same point.

              It is the Administrators responsibility to ensure  that  any  disk  shared  between
              clients uses a cluster-aware filesystem to prevent data corruption.

EXAMPLES

   CREATING ISCSI GATEWAYS
       >/iscsi-targets create iqn.2003-01.com.redhat.iscsi-gw:ceph-igw
              Create a iscsi target name of 'iqn.2003-01.com.redhat.iscsi-gw:ceph-igw', that will
              be used by each gateway node added to the configuration

       >cd /iscsi-targets/iqn.2003-01.com.redhat.iscsi-gw:ceph-igw/gateways
       >create ceph-gw-1 10.172.19.21
       >create ceph-gw-2 10.172.19.22
              Create 2 gateways, using servers ceph-gw-1 and ceph-gw-2. The iSCSI portals will be
              bound to the IP addresses provided. During the registration of a gateway a check is
              performed to ensure the candidate machine has the required IP address available.

   ADDING AN RBD
       >/disks/ create pool=rbd image=disk_1 size=50g
              Create/import a 50g rbd image and register it with each gateway node

   CREATING A CLIENT
       >cd /iscsi-targets/iqn.2003-01.com.redhat.iscsi-gw:ceph-igw/hosts/fR
       >create iqn.1994-05.com.redhat:rh7-client
              Create an iscsi  client  called  'iqn.1994-05.com.redhat:rh7-client'.  The  initial
              client  definition  will  not  have  CHAP  authentication enabled, resulting in red
              highlighting against this clients summary information  in  the  output  of  the  ls
              command.

   ADDING DISKS TO A CLIENT
       >/iscsi-target..eph-igw/hosts> cd iqn.1994-05.com.redhat:rh7-client
       >disk add rbd/disk_1
              The first command navigates to the client's entry in the UI at which point the disk
              or auth sub-commands may be used. In this example the disk subcommand  is  used  to
              mask  disk_1  in  the rbd pool to the iSCSI client. The LUN id associated with this
              device is automatically assigned and maintained by the system.

OTHER COMMANDS

       export mode=[ copy ]
              with the export command a copy of the current configuration can be  exported  as  a
              backup (mode=copy). The resulting output is written to stdout.

       /ceph refresh
              refreshes the ceph information present in the UI

       info   when  run  at  the root of the shell (/), info will show you configuration settings
              such as http mode, API port, local ceph cluster name  and  2ndary  API  trusted  IP
              addresses.

       goto [ gateways | hosts | host-groups | 'bookmark']
              to  ease  navigation within the UI, gwcli automatically creates bookmarks for hosts
              and gateways. This allows you to switch to those sub-trees  in  the  UI  by  simply
              using  'goto  hosts'. The 'goto' command will also work for any other bookmarks you
              create.

FILES

       ~/gwcli.log
              log file maintained by gwcli, recording all changes made via the shell interface in
              a timestamped format.

       ~/.gwcli/history.txt
              log  containing  a  record  of all commands executed within the gwcli shell on this
              system.

AUTHOR

       Written by Paul Cuzner (pcuzner@redhat.com)

REPORTING BUGS

       Report bugs via <https://github.com/ceph/ceph-iscsi-cli/issues>