gwcli(8) Ceph iSCSI Gateway Tools gwcli(8)

gwcli - manage iscsi gateway configuration from the command line

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.

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.

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.

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.

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 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 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.

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.

  















  
>/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.
    

  











  
>/disks/ create pool=rbd image=disk_1 size=50g

  
Create/import a 50g rbd image and register it with each gateway node










>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.











  
>/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.













  

  
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

  

  
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.

  

  
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.











  
~/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.
    

  










Written by Paul Cuzner (pcuzner@redhat.com)








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







  

    Ceph iSCSI Gateway Tools
    23 Jul 2017