7. RESTful APIs

This is a reference for the Feilong RESTful API.

7.1. Response Data Definition

The following table gives a reference of general response data definition of each Feilong RESTful API. In case of encountering an error, those information will be helpful to report bug/issue.

Name	In	Type	Description
overallRC	body	integer	The overall return code for API request.
rc	body	integer	The return code for API request.
rs	body	integer	The reason code for API request.
errmsg	body	string	The error message returned for API request. It can be empty if no error occur.
modID	body	integer	The module ID that causes the error to occur.
output	body	dict	The return data from API request.

The following detail API description will only cover output part as it’s different for each API. (This document is a beta version now)

7.2. Version

Lists version of this API.

7.2.1. Get Feilong version

GET /

• Request:

  No parameters needed.

• Response code:

  HTTP status code 200 on success.

• Response contents:

  Return the version of the zvm cloud connect API.

Name	In	Type	Description
output	body	dict	The return data from API request.
api_version	header	string	API version of Feilong.
min_version	header	string	Min version of Feilong.
max_version	header	string	Max version of Feilong.
version	header	string	Version of Feilong.

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output":
    {
        "api_version": "1.0.",
        "min_version": "1.0",
        "max_version": "1.0",
        "version": "1.0.0"
    }
}

7.3. Token

7.3.1. Create token

POST /token

Get a valid token to perform further request by using Admin-Token which you can think as a combination of username and password.

• Request:

Name	In	Type	Description
X-Admin-Token	header	string	Admin-token, which is stored in /etc/zvmsdk/token.dat. You need put this into header to request for a auth-token. Then you can send a request with this auth-token.

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
X-Auth-Token	header	string	The token returned to client if authorized.

• Response sample:

  Please refer to Token Usage to get more details.

7.4. SMAPI Health

7.4.1. Report health of SMAPI

GET /smapi-healthy

Get health status of the SMAPI.

• Request:

  None

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
SMAPI	body	dict	Status of SMAPI health
totalSuccess	body	integer	The total success calls for SMAPI.
totalFail	body	integer	The total fail calls for SMAPI.
lastSuccess	body	string	The last success call for SMAPI.
lastFail	body	string	The last fail call for SMAPI.
continuousFail	body	integer	The count of continuous fail.
healthy	body	boolean	Whether SMAPI is healthy.

• Response sample:

{
    "SMAPI": {
        "totalSuccess": 0,
        "totalFail": 0,
        "lastSuccess": "",
        "lastFail": "",
        "continueousFail": 0,
        "healthy": True
    }
}

7.5. Guest(s)

Lists, creates, shows details for, updates, and deletes guests.

7.5.1. List Guests

GET /guests

List names of all the guests created by Feilong.

• Request:

  None

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	list	Guests list

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": ["v1", "v2"]
}

7.5.2. Create Guest

POST /guests

Create a vm in z/VM

• Request:

Name	In	Type	Description
guest	body	dict	Guest dict
userid	body	string	The userid of the guest to be created
vcpus	body	integer	vcpus count.
memory	body	integer	Memory size of the guest, in MBytes.
user_profile (Optional)	body	string	Profile of guest, null is also allowed.
disk_list (Optional)	body	list	A list of disks info for the guest It has one dictionary that contain some of the below keys for each disk, the root disk should be the first element in the list.
size	body	string	size of disk, case insensitive, the unit can be in Megabytes (M), Gigabytes (G), or number of cylinders/blocks, for example, please use 512M, 1g or just 2000.
format (Optional)	body	string	Format of disk, can be ext2, ext3, ext4, swap, xfs, none. The file system none means there is no need to create a file system, and in turn no format and partition table will be created, this usually used for some system such as z/OS.
is_boot_disk (Optional)	body	bool	is boot disk or not. For the root disk, this key must be set to indicate the image that will be deployed on this disk.
vdev (Optional)	body	string	when adding mdisk (either add after create or during create guest) use this param to specify the virtual device number. e.g. add this param to dist list as vdev: 0123 will result user direct has something like MDISK 0123
disk_pool (Optional)	body	string	disk pool, if not specified, the disk will be created by using the value from configure file, the format is ECKD:eckdpoolname or FBA:fbapoolname.
max_cpu (Optional)	body	integer	The maximum number of virtual cpus this user can define. The value should be a decimal value between 1 and 64.
max_mem (Optional)	body	string	The maximum size of memory the user can define. The value should be specified by 1-4 bits of number suffixed by either M (Megabytes) or G (Gigabytes). And the number should be a whole number, eg. 512M, 4G.
ipl_from (Optional)	body	string	where the guest IPL from, by default it’s ipl from CONF.zvm.user_root_vdev, and if this value is not empty, the IPL will from given param, for example IPL CMS will IPL from CMS instead of device number.
ipl_param (Optional)	body	string	The param to add to IPL command, e.g. IPL xxx PARM <guest_ipl_param>
ipl_loadparam (Optional)	body	string	The loadparam to add to IPL command, e.g. IPL xxx LOADPARM <guest_ipl_loadparam>
dedicate_vdevs (Optional)	body	list	A list of device vdevs to dedicate to the guest。
loaddev (Optional)	body	dict	The loaddev parms to add in the guest directory.Current supported key includes ‘portname’, ‘lun’ and ‘alterdev’. Both the ‘portname’ and ‘lun’ can specify only one one- to eight-byte hexadecimal value in the range of 0-FFFFFFFFFFFFFFFF. There is ‘alterdev’ added only when the compute node z/VM supports multipath IPL feature.
account (Optional)	body	string	account of guest, useful for guest billing.
comment_list (Optional)	body	list	comment of the user direct.

• Request sample:

{
  "guest":
  {
      "userid": "id001",
      "vcpus": 1,
      "memory": 1024,
      "user_profile": "",
      "disk_list":[
      {
          "size": "1g",
          "is_boot_disk": True,
          "disk_pool": "ECKD:eckdpool1"
      },
      {
          "size": "200000",
          "disk_pool": "FBA:fbapool1",
          "format": "ext3"
      }],
      "max_cpu": 10,
      "max_mem": "32G"
  }
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	list	A list of created disks info for the guest It has one dictionary that contain some of the below keys for each disk.
vdev	body	string	Device number of the disk, 1- to 4- hexadecimal digits.
size	body	string	size of disk, case insensitive, the unit can be in Megabytes (M), Gigabytes (G), for example, please 512M, 1g.
format (Optional)	body	string	Format of disk, can be ext2, ext3, ext4, swap, xfs, none. The file system none means there is no need to create a file system, and in turn no format and partition table will be created, this usually used for some system such as z/OS.
is_boot_disk (Optional)	body	bool	is boot disk or not. For the root disk, this key must be set to indicate the image that will be deployed on this disk.
disk_pool	body	string	disk pool, the format is ECKD:eckdpoolname or FBA:fbapoolname.

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": [{"vdev": "0100",
                "size": "1g",
                "is_boot_disk": True,
                "disk_pool": "ECKD:eckdpool1"},
               {"vdev": "0101",
                "size": "100M",
                "disk_pool": "FBA:fbapool1",
                "format": "ext3"}]
}

7.5.3. Guest add disks

POST /guests/{userid}/disks

Add disks for a guest

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
disk_info	body	dict	A dict to describe disk info.
disk_list (Optional)	body	list	A list of disks info for the guest It has one dictionary that contain some of the below keys for each disk, the root disk should be the first element in the list.
size	body	string	size of disk, case insensitive, the unit can be in Megabytes (M), Gigabytes (G), or number of cylinders/blocks, for example, please use 512M, 1g or just 2000.
format (Optional)	body	string	Format of disk, can be ext2, ext3, ext4, swap, xfs, none. The file system none means there is no need to create a file system, and in turn no format and partition table will be created, this usually used for some system such as z/OS.
is_boot_disk (Optional)	body	bool	is boot disk or not. For the root disk, this key must be set to indicate the image that will be deployed on this disk.
vdev (Optional)	body	string	when adding mdisk (either add after create or during create guest) use this param to specify the virtual device number. e.g. add this param to dist list as vdev: 0123 will result user direct has something like MDISK 0123
disk_pool (Optional)	body	string	disk pool, if not specified, the disk will be created by using the value from configure file, the format is ECKD:eckdpoolname or FBA:fbapoolname.

• Request sample:

{
  "disk_info":
  {
      "disk_list":[
      {
          "size": "1g",
          "is_boot_disk": True,
          "disk_pool": "ECKD:eckdpool1"
      },
      {
          "size": "200000",
          "disk_pool": "FBA:fbapool1",
          "format": "ext3"
      }]
  }
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	list	A list of created disks info for the guest It has one dictionary that contain some of the below keys for each disk.
vdev	body	string	Device number of the disk, 1- to 4- hexadecimal digits.
size	body	string	size of disk, case insensitive, the unit can be in Megabytes (M), Gigabytes (G), for example, please 512M, 1g.
format (Optional)	body	string	Format of disk, can be ext2, ext3, ext4, swap, xfs, none. The file system none means there is no need to create a file system, and in turn no format and partition table will be created, this usually used for some system such as z/OS.
is_boot_disk (Optional)	body	bool	is boot disk or not. For the root disk, this key must be set to indicate the image that will be deployed on this disk.
disk_pool	body	string	disk pool, the format is ECKD:eckdpoolname or FBA:fbapoolname.

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": [{"vdev": "0100",
                "size": "1g",
                "is_boot_disk": True,
                "disk_pool": "ECKD:eckdpool1"},
               {"vdev": "0101",
                "size": "100M",
                "disk_pool": "FBA:fbapool1",
                "format": "ext3"}]
}

7.5.4. Guest configure disks

PUT /guests/{userid}/disks

Configure additional disks for a guest

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
disk_info	body	dict	A dict to describe disk info.
disk_list	body	list	A list of additional disks info for the guest It has one dictionary that contain some of the below keys for each disk
vdev (Optional)	body	string	The device number of the disk, if not specified, zvmsdk will use the next vdev of CONF.zvm.user_root_vdev as the additional disk’s vdev, eg. if CONF.zvm.user_root_vdev is 0100, zvmsdk will use 0101 as the vdev for first additional disk in disk_info, 0102 as the second additional disk’s vdev
format	body	string	Format of disk, can be ext2, ext3, ext4, swap, xfs. The file system none means there is no need to create a file system, and in turn no format and partition table will be created, this usually used for some system such as z/OS.
mntdir (Optional)	body	string	The directory on guest to which the additional disk will be mounted, if not specified, zvmsdk will use /mnt/ephemeral0 as the mount point of first additional disk, /mnt/ephemeral1 as the mount point of second additional disk

• Request sample:

{
  "disk_info":
  {
      "disk_list":[
      {
          "vdev": "0101",
          "format": "ext3",
          "mntdir": "/mnt/0101"
      },
      {
          "vdev": "0102",
          "format": "ext4",
          "mntdir": "/mnt/0102"
      }]
  }
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

  No Response

7.5.5. Guest delete disks

DELETE /guests/{userid}/disks

Delete disks form a guest that in shutdown state

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
vdev_info	body	dict	A dict to describe vdev list to be deleted.
vdev_list	body	list	Disk vdev list of guest It has one list contains the vdev for delete, for example, ['0101','0102']

• Request sample:

{
  "vdev_info":
  {
      "vdev_list":['0101', '0102']
  }
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

  No Response

Note

Not support delete disks when guest is active

7.5.6. Attach Volume

POST /guests/volumes

Attach volume to a vm in z/VM

• Request:

Name	In	Type	Description
info	body	dict	A dict to describe connection info of the volume
connection	body	dict	A dict to describe info of the volume to be operated
assigner_id	body	string	The userid of the guest that the volume will be attached to or detached from.
zvm_fcp	body	list	FCP devices list.
target_wwpn	body	string	World Wide Port Number, must be start with 0x, for example 0x50050763050b073d
target_lun	body	string	Logical Unit Number, must be start with 0x, for example 0x4020400100000000
os_version	body	string	Operating system version, the valid os_version values are: rhel6.x, rhel7.x, sles11.x, sles12.x, ubuntu16.x, all case insensitive, please contact with your cloud administrator if you don’t know the guest’s os version
multipath	body	bool	Multipath service is open or not
mount_point (Optional)	body	string	The symbol link name of the volume device. If not assigned, will be assigned by the os in vm.
is_root_volume (Optional)	body	bool	Volume is bootable or not

• Request sample:

{
  "info":
  {
      "connection":
      {
        "assigner_id": "username",
        "zvm_fcp": "1fc5",
        "target_wwpn": "0x50050763050b073d",
        "target_lun": "0x4020400100000000",
        "os_version": "redhat7",
        "multipath": True,
        "mount_point": "/dev/sdz",
        "is_root_volume": False
      }
  }
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

  No Response

7.5.7. Detach Volume

DELETE /guests/volumes

Detach volume from a vm in z/VM

• Request:

Name	In	Type	Description
info	body	dict	A dict to describe connection info of the volume
connection	body	dict	A dict to describe info of the volume to be operated
assigner_id	body	string	The userid of the guest that the volume will be attached to or detached from.
zvm_fcp	body	list	FCP devices list.
target_wwpn	body	string	World Wide Port Number, must be start with 0x, for example 0x50050763050b073d
target_lun	body	string	Logical Unit Number, must be start with 0x, for example 0x4020400100000000
os_version	body	string	Operating system version, the valid os_version values are: rhel6.x, rhel7.x, sles11.x, sles12.x, ubuntu16.x, all case insensitive, please contact with your cloud administrator if you don’t know the guest’s os version
multipath	body	bool	Multipath service is open or not
mount_point (Optional)	body	string	The symbol link name of the volume device. If not assigned, will be assigned by the os in vm.
is_root_volume (Optional)	body	bool	Volume is bootable or not

• Request sample:

{
  "info":
  {
      "connection":
      {
        "assigner_id": "username",
        "zvm_fcp": "1fc5",
        "target_wwpn": "0x50050763050b073d",
        "target_lun": "0x4020400100000000",
        "os_version": "redhat7",
        "multipath": True,
        "mount_point": "/dev/sdz",
        "is_root_volume": False
      }
  }
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

  No Response

7.5.8. Refresh Volume Bootmap Info

PUT /volumes/volume_refresh_bootmap

Refresh a volume’s bootmap info.

Name	In	Type	Description
fcpchannel	body	list	FCP devices list.
wwpn	body	string	World Wide Port Name IDs.
lun	body	string	Logical Unit Number ID
transportfiles (Optional)	body	string	The files path that used to customize the vm. For RHCOS image, the transportfiles should be the ignition file and it’s required.
guest_networks (Optional)	body	list	Required only if refresh volume bootmap for RHCOS. Network info list of guest. It has one dictionary that contain some of the below keys for each interface. All the keys are optional : ip_addr: the IP address of the interface, cidr is required if ip address is set dns_addr: dns addresses list gateway_addr: gateway address cidr: cidr format nic_vdev: nic device number, 1- to 4- hexadecimal digits mac_addr: mac address nic_id: nic identifier osa_device: OSA device number, 1- to 4- hexadecimal digits hostname: the hostname of the guest

• Request sample:

{'info':
        {
            "fcpchannel": ['5d71'],
            "wwpn": ['5005076802100c1a', '5005076802200c1b'],
            "lun": '0000000000000000',
            "transportfiles": "/path/to/transportfiles",
            "guest_networks": [
                {   
                    "ip_addr": "192.168.95.10",
                    "dns_addr": ["9.0.2.1", "9.0.3.1"],
                    "gateway_addr": "192.168.95.1",
                    "cidr": "192.168.95.0/24",
                    "nic_vdev": "1000",
                    "mac_addr": "02:00:00:12:34:56",
                    "nic_id": "111-222-333",
                    "osa_device": "8080",
                    "hostname": "hostname"
                },
                {
                    "ip_addr": "192.168.95.11",
                    "gateway_addr": "192.168.95.1",
                    "cidr": "192.168.95.0/24",
                    "nic_vdev": "2000",
                    "mac_addr": "02:00:00:12:34:78",
                    "nic_id": "444-555-666"
                }
            ],
        }
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

{
    'errmsg': '',
    'modID': None,
    'output': ['5d71'], ['5005076802400c1a', '5005076802400c1b'],
    'overallRC': 0,
    'rc': 0,
    'rs': 0
}

7.5.9. Get Volume Connector

GET /volumes/conn/{userid}

Get volume connector for z/VM.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
reserve	body	boolean	If or not reserve the FCP devices.

• Response code:

  HTTP status code 200 on success.

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": {
        "zvm_fcp": [],
        "wwpns": []
        "host": ''
    }
}

7.5.10. Get FCP Usage

GET /volumes/fcp/{fcp_id}

Get the FCP usage in database for z/VM.

• Request:

Name	In	Type	Description
fcp_id	path	string	ID of FCP device.

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	list	FCP usage, contains 3 values [userid, reserved, connections]. userid is the userid this fcp belongs to. reserved is 0 or 1, represent the fcp is been used or not. connections is non-negative value, means the count of volumes on this FCP.

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": ['testid', 1, 3]
}

7.5.11. Set FCP Usage

PUT /volumes/fcp/{fcp_id}

Set the FCP usage in database for z/VM.

• Request:

Name	In	Type	Description
fcp_id	path	string	ID of FCP device.
userid	path	string	Guest userid
reserved	body	boolean	If or not reserve the FCP devices.
connections	body	integer	The count of volumes on this FCP device.

• Response code:

  HTTP status code 200 on success.

• Response contents:

  No response.

7.5.12. Get Guests stats including cpu and memory

GET /guests/stats

Get guests cpu, memory information.

• Request:

Name	In	Type	Description
userid	path	string	A string that contains single userid or userids delimited by comma, like id1, id2, id3

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	dict	cpu and memory statics of guest

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": {}
}

7.5.13. Get Guests interface stats

GET /guests/interfacestats

Get guests network interface statistics.

• Request:

Name	In	Type	Description
userid	path	string	A string that contains single userid or userids delimited by comma, like id1, id2, id3

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	dict	vNICs statistics of one guest.

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": {}
}

7.5.14. Get Guests nic info

GET /guests/nics

Get guests nic information, including userid, nic number, vswitch, nic id and comments.

• Request:

Name	In	Type	Description
userid (Optional)	path	string	Guest userid.
nic_id (Optional)	path	string	nic identifier.
vswitch (Optional)	path	string	vswitch name.

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	list	List describing nic information, each nic has one dict to indicate its info, including userid, interface, switch, port id and comments.
userid	body	string	the userid of the nic.
interface	body	string	the device number of the nic.
switch	body	string	vswitch name.
port	body	string	nic identyifier.
comments	body	string	the comments for the nic.

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "output": [{"userid": "id0001",
                "interface": "1000",
                "switch": "vsw01",
                "port": "1111-2222",
                "comments": null}],
    "errmsg": ""
}

7.5.15. Show Guest definition

GET /guests/{userid}

Display the user direct by the given userid.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	dict	Dictionary describing user direct and check info result

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": {"user_direct": ["USER1", "INCLUDE PROFILE"]}
}

7.5.16. Delete Guest

DELETE /guests/{userid}

Delete a guest.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid

• Response code:

  HTTP status code 200 on success.

• Response contents:

  No Response

7.5.17. Get Guest power state from hypervisor

GET /guests/{userid}/power_state_real

Get power state of the guest from hypervisor directly,

no matter the guest is in zcc database or not.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	string	Power status of guest, can be either on or off.

• Response sample:

{
    "rs": 0,
    "overllRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": "off"
}

7.5.18. Get Guest info

GET /guests/{userid}/info

Get running information of guest.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	dict	Status of guest.
max_mem_kb	body	integer	The maximum memory in KBytes can be allocated for this guest.
num_cpu	body	integer	The count of virtual CPUs for the guest.
cpu_time_us	body	integer	The CPU time used in microseconds.
power_state	body	string	Power status of guest, can be either on or off.
mem_kb	body	integer	Meemory size used by the guest, in KBytes.
online_cpu_num	body	integer	The count of online virtual CPUs for the guest.
os_distro	body	string	The os distro information for the guest.
kernel_info	body	string	The kernel information for the guest.

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output":
    {
        "max_mem_kb": 1,
        "num_cpu": 1,
        "cpu_time_us": 0,
        "power_state": "off",
        "mem_kb": 0
    }
}

7.5.19. Get Guest user direct

GET /guests/{userid}/user_direct

Get the user directory info of the given userid from hypervisor.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	dict	Dictionary describing user direct and check info result

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": {"user_direct": ["USER1", "INCLUDE PROFILE"]}
}

7.5.20. Get Guest adapters info

GET /guests/{userid}/adapters

Get adapters information of running guest.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	list	A list of adapters info for the guest It has one or more dictionary that contain some of the below keys, one dictionary represent for one adapter. each adapter.
lan_owner	path	string	Guest userid
lan_name	path	string	vswitch name.
adapter_address (Optional)	body	string	nic device number, 1- to 4- hexadecimal digits.
adapter_status	body	string	status of adapter, 2 hexadecimal digits. 02 means normal.
mac_address (Optional)	body	string	Mac address, it is only used when changing the guest’s user direct. Format should be xx:xx:xx:xx:xx:xx, and x is a hexadecimal digit.
mac_ip_address (Optional)	body	string	ip address.
mac_ip_version	body	string	version of IP address, 4 means IPV4, 6 means IPV6.

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output":
    {
        u'adapters': [{u'lan_owner': u'SYSTEM',
                       u'adapter_address': u'1000',
                       u'lan_name': u'VSC11590',
                       u'adapter_status': u'02',
                       u'mac_address': u'02:55:36:5D:48:57',
                       u'mac_ip_version': u'4',
                       u'mac_ip_address': u'9.152.85.152'}]
    }
}

7.5.21. Create Guest nic

POST /guests/{userid}/nic

Create a virtual nic on giving guest.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
nic	body	dict	The information which is used to set nic device number
vdev (Optional)	body	string	nic device number, 1- to 4- hexadecimal digits. null is also allowed.
nic_id (Optional)	body	string	nic identifier
mac_addr (Optional)	body	string	Mac address, it is only used when changing the guest’s user direct. Format should be xx:xx:xx:xx:xx:xx, and x is a hexadecimal digit.
active (Optional)	body	bool	Whether the change will apply to the active guest.

• Request sample:

{
  "nic":
  {
      "vdev": "1000",
      "nic_id": "1111-2222-3333",
      "mac_addr": "12:34:56:AA:BB:CC",
      "active": True
  }
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

7.5.22. Create network interface

POST /guests/{userid}/interface

Create one or more network interfaces on giving guest.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
interface	body	dict	The information which is used to describe network interface.
os_version	body	string	Operating system version, the valid os_version values are: rhel6.x, rhel7.x, sles11.x, sles12.x, ubuntu16.x, rhcos4.x, all case insensitive, please contact with your cloud administrator if you don’t know the guest’s os version
guest_networks	body	list	Network info list of guest. It has one dictionary that contain some of the below keys for each interface. All the keys are optional : ip_addr: the IP address of the interface, cidr is required if ip address is set dns_addr: dns addresses list gateway_addr: gateway address cidr: cidr format nic_vdev: nic device number, 1- to 4- hexadecimal digits mac_addr: mac address nic_id: nic identifier osa_device: OSA device number, 1- to 4- hexadecimal digits
active (Optional)	body	bool	Whether the change will apply to the active guest.

• Request sample:

{
  "interface":
  {
      "os_version": "rhel7.2",
      "guest_networks": [
      {   
          "ip_addr": "192.168.95.10",
          "dns_addr": ["9.0.2.1", "9.0.3.1"],
          "gateway_addr": "192.168.95.1",
          "cidr": "192.168.95.0/24",
          "nic_vdev": "1000",
          "mac_addr": "02:00:00:12:34:56",
          "nic_id": "111-222-333",
          "osa_device": "8080"
      },
      {
          "ip_addr": "192.168.95.11",
          "gateway_addr": "192.168.95.1",
          "cidr": "192.168.95.0/24",
          "nic_vdev": "2000",
          "mac_addr": "02:00:00:12:34:78",
          "nic_id": "444-555-666"
      }],
      "active": "True"
  }
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

7.5.23. Delete network interface

DELETE /guests/{userid}/interface

Delete one network interface on giving guest.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
interface	body	dict	The information which is used to describe network interface.
os_version	body	string	Operating system version, the valid os_version values are: rhel6.x, rhel7.x, sles11.x, sles12.x, ubuntu16.x, all case insensitive, please contact with your cloud administrator if you don’t know the guest’s os version
vdev	body	string	the device number of the nic.
active (Optional)	body	bool	Whether the change will apply to the active guest.

• Request sample:

{
  "interface":
  {
      "os_version": "rhel7.2",
      "vdev": "1000",
      "active": True
  }
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

7.5.24. Start guest

Start a guest.

POST /guests/{userid}/action

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
action	body	string	Take start action on guest.

• Request sample:

{
   "action": "start"
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

7.5.25. Stop guest

Stop a guest.

POST /guests/{userid}/action

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
action	body	string	Take stop action on guest.

• Request sample:

{
   "action": "stop"
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

7.5.26. Softstop guest

Stop a guest gracefully, it will firstly shutdown the os on vm, then stop the vm.

POST /guests/{userid}/action

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
action	body	string	Take softstop action on guest.

• Request sample:

{
   "action": "softstop"
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

7.5.27. Pause guest

Pause a guest.

POST /guests/{userid}/action

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
action	body	string	Take pause action on guest.

• Request sample:

{
   "action": "pause"
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

7.5.28. Unpause guest

Unpause a guest.

POST /guests/{userid}/action

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
action	body	string	Take unpause action on guest.

• Request sample:

{
   "action": "unpause"
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

7.5.29. Reboot guest

Reboot a guest, this will use ‘reboot’ command on the given guest.

POST /guests/{userid}/action

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
action	body	string	Take reboot action on guest.

• Request sample:

{
   "action": "reboot"
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

7.5.30. Reset guest

Reset a guest, this will first gracefully logoff the guest from z/VM it is running on, then log on the guest and IPL.

POST /guests/{userid}/action

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
action	body	string	Take reset action on guest.

• Request sample:

{
   "action": "reset"
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

7.5.31. Get guest console output

POST /guests/{userid}/action

Get console output of guest.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
action	body	string	Take get_console_output action on guest.

• Request sample:

{
   "action": "get_console_output"
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

  • output: console_output

Note

In order to retrieve the console log from guest vm, you must add user direct statment “COMMAND SP CONS * START” to the profile that used to deploy guest vm, otherwise no console log collected for the guest vm.

7.5.32. Live migration of guest

POST /guests/{userid}/action

Live migrate guest in z/VM SSI cluster.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
action	body	string	Take live_migrate_vm action on guest.
dest_zcc_userid (Optional)	body	string	The userid of zcc on destination node. Required if lgr_action equals move.
destination	body	string	The system ID of the z/VM system to which the specified vm will be relocated or tested.
parms (Optional)	body	dict	A dictionary of options for relocation.
lgr_action	body	string	Indicates the action is test or move for the live migration. test will test the guest is eligible to live migrate or not. move will live migrate the guest immediately.

• Request sample:

{
   "action": "live_migrate_vm",
   "dest_zcc_userid": "destuid",
   "destination": "destnode",
   "parms": {
       "maxtotal": 360,
       "maxquiesce": 60,
       "immediate": "YES",
   },
   "operation": "move",
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

7.5.33. Guest register

POST /guests/{userid}/action

Register guest to be managed by Feilong.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
action	body	string	Take register_vm action on guest.
meta	body	string	The metadata of the vm to be registered.
net_set	body	string	Guest network configured or not. 1 means configured, 0 means not configured. Default as 1.
port (Optional)	body	dict	The dict of virtual interface port id and mac id

• Request sample:

{
   "action": "register_vm",
   "meta": '{"os_version": "sles12sp3"}',
   "net_set": "1",
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

7.5.34. Guest deregister

POST /guests/{userid}/action

Deregister guest to be managed by Feilong.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
action	body	string	Take deregister_vm action on guest.

• Request sample:

{
   "action": "deregister_vm",
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

7.5.35. Live resize CPUs of guest

POST /guests/{userid}/action

Live resize CPUs of guest.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
action	body	string	Take live_resize_cpus action on guest.
cpu_cnt	body	integer	The number of virtual cpus that the guest should have after resize. The value should be an positive integer between 1 and 64.

• Request sample:

{
   "action": "live_resize_cpus",
   "cpu_cnt": 4
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

Note

• Currently only increasing CPU count is supported, decreasing is not supported.

• The guest to be live resized must be active and managed by Feilong.

• If live resize finished successfully, both the active CPU number and the number of defined CPUs in user directory would be updated to the requested so that the CPU count would persist even after the guest is restarted.

• If requested CPU count is smaller than the current active CPU count, then the API would return error immediately since lively decrease CPU count is not supported.

• If requested CPU count is larger than the defined CPU number in user directory, this API would increase the CPU number in user directory to requested count. Otherwise, this API would decrease the CPU number in user directory to the requested count.

• To live resize a guest, the guest must have maximum CPU count defined in user directory entry with “MACHINE ESA xx” where ‘xx’ is the maximum CPU count. The resize CPU count can’t exceed the maximum CPU count.

• For guests created by Feilong after version 1.2.0, the maximum CPU count is defined when the guest is created. The maximum CPU count is set by the configuration “user_default_max_cpu” in [zvm] section and can be overriden by the parameter “max_cpu” when creating the guest. e.g, the following configuration would define the default maximum CPU count as 64.

  [zvm]
  user_default_max_cpu=64
  

7.5.36. Resize CPUs of guest

POST /guests/{userid}/action

Resize CPUs of guest.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
action	body	string	Take resize_cpus action on guest.
cpu_cnt	body	integer	The number of virtual cpus that the guest should have after resize. The value should be an positive integer between 1 and 64.

• Request sample:

{
   "action": "resize_cpus",
   "cpu_cnt": 4
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

Note

• Both increasing and decreasing CPU count are supported.

• The target guest can be in either ‘on’ or ‘off’ status, the definition change would take into effects after logoff and re-logon (reset).

7.5.37. Live resize memory of guest

POST /guests/{userid}/action

Live resize memory of guest.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
action	body	string	Take live_resize_mem action on guest.
size	body	string	The size of memory that the guest should have after resize. The value should be specified by 1-4 bits of number suffixed by either M (Megabytes) or G (Gigabytes). And the number should be an integer, eg. 512M, 4G.

• Request sample:

{
   "action": "live_resize_mem",
   "size": "4096m"
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

Note

• Currently only increasing memory size is supported, decreasing is not supported.

• The guest to be live resized must be active and managed by Feilong.

• If live resize finished successfully, both the active memory and the initial memory defined in user directory would be updated to the requested size so that the change would persist even after the guest is restarted.

• If requested memory size is smaller than the current active memory, then the API would return error immediately since lively decrease memory size is not supported.

• If requested memory size is larger than the defined initial memory in user directory, this API would increase the initial memory defined in user directory to requested size. Otherwise, this API would decrease the memory in user directory to the requested size.

• The resize memory size can’t exceed the maximum memory defined in user directory.

• The maximum memory size is defined when the guest is created. It is set by the configuration “user_default_max_memory” in [zvm] section and can be overriden by the parameter “max_mem” when creating the guest. e.g, the following configuration would define the default maximum memory size as 64G.

  [zvm]
  user_default_max_memory=64g
  

7.5.38. Resize memory of guest

POST /guests/{userid}/action

Resize memory of guest.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
action	body	string	Take resize_mem action on guest.
size	body	string	The size of memory that the guest should have after resize. The value should be specified by 1-4 bits of number suffixed by either M (Megabytes) or G (Gigabytes). And the number should be an integer, eg. 512M, 4G.

• Request sample:

{
   "action": "resize_mem",
   "size": "8g"
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

Note

• Both increasing and decreasing memory size are supported.

• The target guest can be in either ‘on’ or ‘off’ status, the definition change would take into effects after logoff and re-logon (reset).

7.5.39. Deploy guest

POST /guests/{userid}/action

After guest created, deploy image onto the guest.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
action	body	string	Take deploy action on guest.
image	body	string	Image name that can be uniquely identify an image.
transportfiles (Optional)	body	string	The files path that used to customize the vm. For RHCOS image, the transportfiles should be the ignition file and it’s required.
remotehost (Optional)	body	string	The server that the transportfiles located, if remotehost is not specified, will deploy with the transport file in local server, otherwise, the format is username@ip, for example, nova@9.x.x.x or username@hostname eg.``test@test.ibm.com``
vdev (Optional)	body	string	Device number to which the image will be deployed, 1- to 4- hexadecimal digits. null is also allowed.
hostname (Optional)	body	string	hostname of the guest. Will be ignored if transportfiles specified. null is also allowed.
skipdiskcopy (Optional)	body	boolean	whether to skip the copy of image to disk. Default value if False. If the value is True, the image_name specified should be the os version. If the value is False, the image_name specified should be the name of the image to be used to copy to the root disk.

• Request sample:

{
  "action": "deploy",
  "image": "image1",
  "transportfiles": "/data/openstack/nova/instances/opnstk1/fp1t001d/cfgdrive.tgz",
  "remotehost": "nova@192.168.99.1",
  "vdev": "0100"
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

7.5.40. Capture guest

POST /guests/{userid}/action

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
action	body	string	Take capture action on guest.
image	body	string	Image name that can be uniquely identify an image.
capture_type (Optional)	body	string	The type of capture: rootonly: indicate just root device will be captured, this is the default one alldisks: indicate all the devices of the userid will be captured
compress_level (Optional)	body	integer	The compression level of the image, default value is 6

• Request sample:

{
  "action": "capture",
  "image": "capturedimage",
  "capture_type": "rootonly",
  "compress_level": 6
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

7.5.41. Grow root volume of guest

POST /guests/{userid}/action

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
action	body	string	Take grow_root_volume action on guest.
os_version	body	string	Operating system version, the valid os_version values are: rhel6.x, rhel7.x, sles11.x, sles12.x, ubuntu16.x, all case insensitive, please contact with your cloud administrator if you don’t know the guest’s os version

• Request sample:

{
  "action": "grow_root_volume",
  "os_version": "RHEL7.8"
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

7.5.42. Get Guest power state

GET /guests/{userid}/power_state

Get power state of the guest.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid

• Response code:

  HTTP status code 200 on success. HTTP status code 404 if guest is not in zcc database or it is in zcc database but its user directory does not exist.

• Response contents:

Name	In	Type	Description
output	body	string	Power status of guest, can be either on or off.

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": "off"
}

7.5.43. Update Guest nic

PUT /guests/{userid}/nic/{vdev}

Couple or uncouple nic with vswitch on the guest.

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
vdev	path	string	nic device number, 1- to 4- hexadecimal digits.
info	body	dict	The info used to describe the couple/uncouple action.
couple	body	bool	couple or uncouple action.
active (Optional)	body	bool	Whether the change will apply to the active guest.
vswitch (Optional)	body	string	vswitch name.
vlan_id	body	integer	The VLAN ID. This can be any of the value between -1 or 1-4094.

• Request sample:

{
  "info":
  {
      "couple": True,
      "active": False,
      "vswitch": "vs_name"
  }
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

  No response.

7.5.44. Delete Guest nic

DELETE /guests/{userid}/nic/{vdev}

• Request:

Name	In	Type	Description
userid	path	string	Guest userid
vdev	path	string	nic device number, 1- to 4- hexadecimal digits.
active (Optional)	body	bool	Whether the change will apply to the active guest.

• Response code:

  HTTP status code 200 on success.

• Response contents:

  No response.

7.6. Host

Get guests list, info from host (hypervisor) running on.

7.6.1. Get Guests List

GET /host/guests

List names of all the guests on the host.

• Request:

  None

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	list	Guests list

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": ["v1", "v2"]
}

Get info from host (hypervisor) running on.

7.6.2. Get Host Info

GET /host

Get host information.

• Request:

  No parameters needed.

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	dict	The dict of host information.

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": 
    {
         "disk_available": 3057,
         "ipl_time": "IPL at 06/02/17 11:07:10 EDT",
         "vcpus_used": 6,
         "hypervisor_type": "zvm",
         "vcpus": 6,
         "zvm_host": "OPNSTK2",
         "memory_mb": 51200.0,
         "cpu_info": {
              "cec_model": "2817",
              "architecture": "s390x"
         },
         "disk_total": 3623,
         "zcc_userid": "ZCCUID",
         "hypervisor_hostname": "OPNSTK2",
         "hypervisor_version": 640,
         "disk_used": 566,
         "memory_mb_used": 0.0
    }
}

7.6.3. Get Host disk pool info

GET /host/diskpool

Get disk pool information(or the free space among all volumes in the disk pool) on the host.

• Request:

Name	In	Type	Description
poolname (Optional)	path	string	The pool name to get pool information from
details (Optional)	path	boolean	get the free space of all volumes on the disk pool or not.

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
disk_available	body	int	The total available size of the disks in the pool in Gigabytes(G).
disk_total	body	int	The total size of the pool in Gigabytes (G).
disk_used	body	int	The size of used disks in the pool in Gigabytes(G).

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "output":
    {
         "disk_available": 3060,
         "disk_total": 3623,
         "disk_used": 563
    },
    "errmsg": ""
}

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "output":
    {
        {
            'ICICPL':
             [
                 {
                     'volume_name': 'vol1',
                     'device_type': 'type1',
                     'start_cylinder': 13456,
                     'free_size': 2345,
                     'dasd_group': 'ICICPL',
                     'region_name': 'vol1'
                 },
                 {
                      'volume_name': 'vol2',
                      'device_type': 'type1',
                      'start_cylinder': '22456',
                      'free_size': 12980,
                      'dasd_group': 'ICICPL',
                      'region_name': 'vol2'
                  }
              ]
        }
    },
    "errmsg": ""
}

7.6.4. Get host disk pool volume names

GET /host/diskpool_volumes

Get volume list of the diskpool on the host.

• Request:

Name	In	Type	Description
poolname (Optional)	path	string	The pool name to get pool information from

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
diskpool_volumes	body	string	The volume list of the diskpool

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "output":
    {
         "diskpool_volumes": "IAS100 IAS101",
    },
    "errmsg": ""
}

7.6.5. Get host volume info

GET /host/volume

Get the volume info on the host.

• Request:

Name	In	Type	Description
volumename	path	string	The name of the volume

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
volume_type	body	string	The type of the volume
volume_size	body	int	The disk size of the volume

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "output":
    {
         "volume_type": "3390-54",
         "volume_size": "60102"
    },
    "errmsg": ""
}

7.6.6. Get Host SSI Cluster Info

GET /host/ssi

Get the SSI(Single System Image) cluster information of the host.

• Request:

  No parameters needed.

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	list	If the host is an SSI cluster member, it returns a list of SSI cluster information. If current host is not an SSI cluster member, it returns an empty list.

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output":
    [
         "ssi_name = ZVM2SSI",
         "ssi_mode = Stable",
         "ssi_pdr = IAS7CM_on_139E",
         "cross_system_timeouts = Enabled",
         "output.ssiInfoCount = 2",
         "",
         "member_slot = 1",
         "member_system_id = OPNSTK2",
         "member_state = Joined",
         "member_pdr_heartbeat = 01/12/2022_04:17:54",
         "member_received_heartbeat = 01/12/2022_04:17:54",
         "",
         "member_slot = 2",
         "member_system_id = OPNSTK3",
         "member_state = Joined",
         "member_pdr_heartbeat = 01/12/2022_04:17:35",
         "member_received_heartbeat = 01/12/2022_04:17:35",
         ""
    ]
}

7.7. Image(s)

Lists, creates, shows details for, updates, and deletes images.

7.7.1. List images

GET /images

Get the list of image info in image repository.

• Request:

Name	In	Type	Description
imagename (Optional)	path	string	Retrieve the specified image information, if not specified, when list image, all images information will be returned.

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	list	The image info for specific image or all images, each image has one dict to indicate its info
imagename	body	string	Image name that can be uniquely identify an image.
imageosdistro	body	string	Operating system version, the valid os_version values are: rhel6.x, rhel7.x, sles11.x, sles12.x, ubuntu16.x, rhcos4.x, all case insensitive, please contact with your cloud administrator if you don’t know the guest’s os version
md5sum	body	string	md5sum for the specific image.
disk_size_units	body	string	The image’s root disk size in units CYL or BLK, eg 3338:CYL or 614200:BLK.
image_size_in_bytes	body	string	Physical image size in bytes eg 5120000
type	body	string	How the image is generated, if it captured from root disk the type is netboot.
comments	body	string	the comments for the image
last_access_time	body	float	the time stamp of last access time of this image the seconds count after 1970 and is generated from python time module.

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "output": [{"imagename": "image1",
                "imageosdistro": "rhel7.2",
                "md5sum": "52014cd658cea6ed4005fb25885e30e2",
                "disk_size_units": "0:CYL",
                "image_size_in_bytes": "55",
                "type": "netboot",
                "comments": null}],
    "errmsg": ""
}

7.7.2. Create image

POST /images

Import an image into image repository

• Request:

Name	In	Type	Description
image	body	dict	The image info dict.
image_name	body	string	Image name that can be uniquely identify an image.
url	body	string	The location of the image to be imported, support import image from 3 types location, local file system: eg. file:///opt/images/import.img. http server: eg. http://192.168.2.1/path/to/import.img file system on remote host: in this case both url and remote_host parameter should be specified
image_meta	body	dict	The metadata which describes image, the valid keys are os_version, md5sum and disk_type, os_version is required key, the valid os_version values are: rhel6.x, rhel7.x, sles11.x, sles12.x, ubuntu16.x, rhcos4.X, all case insensitive, please contact with your cloud administrator if you don’t know the image’s os version. disk_type is required if os_version is rhcos4, the valid disk_type values are: DASD, SCSI.
remote_host (Optional)	body	string	The server from where the image will be import, if remote_host is None, the image will be import from the url in local server, otherwise, the format is username@ip, for example, nova@9.x.x.x or username@hostname, for example, test@test.ibm.com

• Request sample:

{
  "image": 
  {
     "image_name": "image1",
     "url": "file:///image1",
     "image_meta": {"os_version": "rhel6.2"},
     "remote_host": "nova@9.x.x.x"
  }
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

  No response.

7.7.3. Export image

PUT /images/{name}

Export the image to the specified location.

• Request:

Name	In	Type	Description
name	path	string	Image name that can be uniquely identify an image.
location	body	dict	The dictionary to indicate the location info of image to be exported
dest_url	body	string	The location of the exported image, support export to 2 types location, local file system: eg. file:///opt/images/export.img file system on remote host: in this case both dest_url and remote_host parameter should be specified
remote_host (Optional)	body	string	The server that the image will be export to, if remote_host is None, the image will be stored in the dest_path in local server, otherwise, the format is username@ip, for example, nova@9.x.x.x or username@hostname eg.``test@test.ibm.com``.

• Request sample:

{
  "location": 
  {
     "dest_url": "file:///export/to/image1",
     "remote_host": "test@test.ibm.com"
  }
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	dict	The dict contains image info after export.

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": {"image_name": "name1",
               "image_path": "/tmp/images/name1",
               "os_version": "rhel6",
               "md5sum": "121212314231"}
}

7.7.4. Get root disk size of image

GET /images/{name}/root_disk_size

Get the root disk size of the image.

• Request:

Name	In	Type	Description
name	path	string	Image name that can be uniquely identify an image.

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	string	The image’s root disk size in units CYL or BLK, eg 3338:CYL or 614200:BLK.

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "output": "3338:CYL",
    "errmsg": ""
}

7.7.5. Delete image

DELETE /images/{name}

Delete an image.

• Request:

Name	In	Type	Description
name	path	string	Image name that can be uniquely identify an image.

• Response code:

  HTTP status code 200 on success.

• Response contents:

  No response.

7.8. VSwitch

Lists, creates, updates, and deletes vswitch.

7.8.1. Create vswitch

POST /vswitches

Create a new vswitch.

• Request:

Name	In	Type	Description
name	body	string	vswitch name.
rdev (Optional)	body	string	The real device number, a maximum of three devices. null is also allowed.
controller (Optional)	body	string	The vswitch’s controller. It could be userid or “*” to specifies any available controller.
connection (Optional)	body	string	Connection type option : CONnect: Activate the real device connection. DISCONnect: Do not active the real device connection. NOUPLINK: the vswitch will never have connectivity through.
network_type (Optional)	body	string	Specifies the transport mechanism to be used for switch, as follow:IP, ETHERNET, default is ETHERNET.
router (Optional)	body	string	Connection type option : NONROUTER: The OSA-Express device identified in real_device_address= will not act as a router to the vswitch. PRIROUTER: The OSA-Express device identified in real_device_address= will act as a primary router to the vswitch. Note: If the network_type is ETHERNET, this value must be unspecified, otherwise, if this value is unspecified, default is NONROUTER
vid (Optional)	body	string, integer	The VLAN ID. This can be any of the following values: UNAWARE, AWARE or 1-4094.
port_type (Optional)	body	string	Port type : ACCESS: The default porttype attribute for guests authorized for the virtual switch. The guest is unaware of VLAN IDs and sends and receives only untagged traffic TRUNK: The default porttype attribute for guests authorized for the virtual switch. The guest is VLAN aware and sends and receives tagged traffic for those VLANs to which the guest is authorized. If the guest is also authorized to the natvid, untagged traffic sent or received by the guest is associated with the native VLAN ID (natvid) of the virtual switch.
gvrp (Optional)	body	string	gvrp : GVRP: Indicates that the VLAN IDs in use on the virtual switch should be registered with GVRP-aware switches on the LAN. This provides dynamic VLAN registration and VLAN registration removal for networking switches. This eliminates the need to manually configure the individual port VLAN assignments. NOGVRP: Do not register VLAN IDs with GVRP-aware switches on the LAN. When NOGVRP is specified VLAN port assignments must be configured manually
queue_mem (Optional)	body	integer	A number between 1 and 8, specifying the QDIO buffer size in megabytes
native_vid (Optional)	body	integer	The native vlan id, 1-4094 or null.
persist (Optional)	body	boolean	Whether create the vswitch in the permanent configuration for the system.

• Request sample:

{
  "vswitch":
  {
      "name": "vs_name",
      "rdev": "FF00",
      "controller": "*",
      "connection": "CONnect",
      "network_type": "ETHERNET",
      "router": "NONROUTER",
      "vid": "UNAWARE",
      "port_type": "ACCESS",
      "gvrp": "GVRP",
      "queue_mem": 8,
      "native_vid": 1,
      "persist": True
  }
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

  No response.

7.8.2. List vswitches

GET /vswitches

Get the list of vswitch name on the host

• Request:

  No parameter needed.

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	list	List of vswitches.

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": ["v1", "v2"]
}

7.8.3. GET vswitch details

GET /vswitches/{name}

Get the details of a vswitch

• Request:

Name	In	Type	Description
name	path	string	vswitch name.

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	dict	The vswitch info for specific vswitch

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "output": {
              "switch_name": "TESTVSW",
              "lag_group": "(NOGRP)",
              "port_type": "NONE",
              "vlan_id": "0000",
              "queue_memory_limit": "8",
              "gvrp_request_attribute": "NOGVRP",
              "MAC_protect": "UNSPECIFIED",
              "mac_address": "02-00-0C-00-00-09",
              "gvrp_enabled_attribute": "NOGVRP",
              "lag_interval": "0",
              "IP_timeout": "5",
              "vlan_awareness": "UNAWARE",
              "isolation_status": "NOISOLATION",
              "native_vlan_id": "0000",
              "user_port_based": "USERBASED",
              "transport_type": "ETHERNET",
              "link_ag": "LAG",
              "switch_type": "QDIO",
              "switch_status": "OSA device ready.",
              "routing_value": "NA",
              "VLAN_counters": "E)",
              "real_devices": {"8070":
                                     {"dev_status": "Device is active.",
                                      "controller": "DTCVSW1",
                                      "port_name": "NONE",
                                      "dev_err": "No error.",
                                      "vdev": "0600"}},
              "authorized_users":
                     {"UB160120":
                             {"vlan_ids": [], "prom_mode": "NOPROM",
                              "port_num": "0000", "osd_sim": "NOOSDSIM",
                              "vlan_count": 0},
                      "OPNCLOUD":
                             {"vlan_ids": [], "prom_mode": "NOPROM",
                              "port_num": "0000", "osd_sim": "NOOSDSIM",
                              "vlan_count": 0}},
              "adapters":
                     {
                      "UB160120_1009": {"mac": "02-00-0C-00-01-2D", "type": "QDIO"},
                      "OPNCLOUD_0700": {"mac": "02-00-0C-00-00-0C", "type": "QDIO"}}
              },
    "errmsg": ""
}

7.8.4. Grant user to vswitch

PUT /vswitches/{name}

Grant an user to access vswitch

• Request:

Name	In	Type	Description
name	path	string	vswitch name.
vswitch	body	dict	The vswitch update info.
grant_userid	path	string	Guest userid

• Request sample:

{
   "vswitch":
   {
      "grant_userid": "FVTUSER1"
   }
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

  No response.

7.8.5. Revoke user from vswitch

PUT /vswitches/{name}

Revoke the user access from vswitch

• Request:

Name	In	Type	Description
name	path	string	vswitch name.
vswitch	body	dict	The vswitch update info.
revoke_userid	path	string	Guest userid

• Request sample:

{
   "vswitch":
   {
      "revoke_userid": "FVTUSER1"
   }
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

  No response.

7.8.6. Set user VLANID to vswitch

PUT /vswitches/{name}

Set vlan id for user when connecting to the vswitch

• Request:

Name	In	Type	Description
name	path	string	vswitch name.
vswitch	body	dict	The vswitch update info.
user_vlan_id	body	dict	A dict to describe guest userid and vlanid.
userid	path	string	Guest userid
vlanid	body	integer	The VLAN ID. This can be any of the value between -1 or 1-4094.

• Request sample:

{
   "vswitch":
   {
      "user_vlan_id": {
          "userid": "FVTUSER1"
          "vlanid": 100
      }
   }
}

• Response code:

  HTTP status code 200 on success.

• Response contents:

  No response.

7.8.7. Delete vswitch

DELETE /vswitches/{name}

Delete a vswitch by using given name.

• Request:

Name	In	Type	Description
name	path	string	vswitch name.

• Response code:

  HTTP status code 200 on success.

• Response contents:

  No response.

7.9. Files

Imports and exports raw file data.

These operations may be restricted to Feilong administrators.

7.9.1. Import file

PUT /files

Import binary file data to Feilong. Internal use Only.Please set the Content-Type of the request header to application/octet-stream. The body contains the binary data.

• Request:

Name	In	Type	Description
Content-type	header	string	The media type descriptor for the request body. Use ‘application/octet-stream’

• Example call:

  curl http://192.168.99.3:8888/files -i -X PUT -H “X-Auth-Token: $token” -H

  “Content-Type: application/octet-stream” –data-binary @/root/testfile

• Response code:

  HTTP status code 200 on success.

• Response contents:

Name	In	Type	Description
output	body	dict	Dictionary describing the file import status and result
dest_url	body	string	The location of file after imported on Feilong. For example, ‘file:///var/lib/zvmsdk/files/imported/be919b98-8408-11e8-b9fe-020001000053’
filesize_in_bytes	body	int	The physical file size in bytes
md5sum	body	string	The md5sum of the file after imported

• Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": {"filesize_in_bytes": 7614,
               "md5sum": "8aa3752079b9dc2269cdc44a7185e287",
               "dest_url": "file:///var/lib/zvmsdk/files/imported/be919b98-8408-11e8-b9fe-020001000053"}
}

7.9.2. Export file

POST /files

Export file from Feilong, internal use only.

• Request:

Name	In	Type	Description
source_file	body	string	The path of the file to be exported, eg. ‘/root/testfile’

• Response code:

  HTTP status code 200 on success.

The response body contains the raw binary data that represents the actual file. The Content-Type header contains the application/octet-stream value.