Provided by: ceph-iscsi_3.6-3_all 
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>