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 occurred.
modID	body	integer	The module ID that caused 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 Feilong 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	Minimum version of Feilong.
max_version	header	string	Maximum 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¶

Management of authentication token.

7.3.1. Create token¶

POST /token

Get a valid token to perform further requests by using an 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, stored in `/etc/zvmsdk/token.dat`. You need to put this into the header to request for an authentication token. Then you can send a request with this authentication 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 Securing Connections with Tokens to get more details.

7.4. SMAPI Health¶

Check health of SMAPI layer used by Feilong.

7.4.1. Report health of SMAPI¶

GET /smapi_health

Get health status of SMAPI.

Request:

None
Response code:

HTTP status code 200 on success.
Response contents:

Name	In	Type	Description
output	body	dict	SMAPI health report.
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 fails.
healthy	body	boolean	Whether SMAPI is healthy.

Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": {
        "totalSuccess": 0,
        "totalFail": 0,
        "lastSuccess": "",
        "lastFail": "",
        "continuousFail": 0,
        "healthy": True
    }
}

Note:

Old API call GET /smapi-healthy is deprecated.

7.5. Guest(s)¶

Management of z/VM guests and their peripherals.

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 disk information 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 `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 that there is no need to create a file system, and in turn no format and partition table will be created, this is usually used for some systems such as z/OS.
is_boot_disk (Optional)	body	boolean	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 a minidisk (either after creating or during creation of guest), use this parameter to specify the virtual device number. e.g. adding this parameter to disk list as `vdev: 0123` will make user directory have something like `MDISK 0123`.
disk_pool (Optional)	body	string	Disk pool. If not specified, the disk will be created by using the value from configuration 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 an integer 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 to 4 digits suffixed by either M (megabytes) or G (gigabytes). The number should be a whole number, e.g. 512M or 4G.
ipl_from (Optional)	body	string	Where the guest will IPL from. By default, it will IPL from `CONF.zvm.user_root_vdev`. If this value is not empty, it will IPL from the given parameter, for example `IPL CMS` will IPL from CMS instead of device number.
ipl_param (Optional)	body	string	The parameter to add to IPL command, e.g. IPL xxx PARM <guest_ipl_param>.
ipl_loadparam (Optional)	body	string	The load parameter 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 parameters to add in the guest directory. Current supported keys include `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 directory.

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 information 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) or gigabytes (G), for example `512M` or `1g`.
format (Optional)	body	string	Format of disk, can be `ext2`, `ext3`, `ext4`, `swap`, `xfs`, `none`. The file system `none` means that there is no need to create a file system, and in turn no format and partition table will be created, this is usually used for some systems such as z/OS.
is_boot_disk (Optional)	body	boolean	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. Get guest minidisks info¶

GET /guests/{userid}/disks

List characteristics of all disks of a guest.

Request:

None
Response code:

HTTP status code 200 on success.
Response contents:

Name	In	Type	Description
userid	path	string	Guest userid.
minidisks (Optional)	body	list	A list of disks information for the guest. Each entry in this list describes a minidisk and is a dictionary that contains some of the below keys.
vdev	body	string	The virtual device number of the disk.
rdev	body	string	The real device number of the disk.
access_type	body	string	Type of access to the disk, either `R/O` or `R/W`.
device_size	body	integer	The size of the disk, without unit.
device_units	body	string	The unit for the size of the disk, for example `Cylinders`.
volume_label	body	string	The volume label of the disk.

Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": {
        "minidisks": [{'vdev': '0100',
                       'rdev': '6018',
                       'access_type': 'R/W',
                       'device_type': '3390',
                       'device_size': 29128,
                       'device_units': 'Cylinders',
                       'volume_label': 'VM6018'}]

    }
}

7.5.4. Guest add disks¶

POST /guests/{userid}/disks

Add disks to a guest.

Request:

Name	In	Type	Description
userid	path	string	Guest userid.
disk_info	body	dict	A dict to describe disk information.
disk_list (Optional)	body	list	A list of disk information 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 `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 that there is no need to create a file system, and in turn no format and partition table will be created, this is usually used for some systems such as z/OS.
is_boot_disk (Optional)	body	boolean	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 a minidisk (either after creating or during creation of guest), use this parameter to specify the virtual device number. e.g. adding this parameter to disk list as `vdev: 0123` will make user directory have something like `MDISK 0123`.
disk_pool (Optional)	body	string	Disk pool. If not specified, the disk will be created by using the value from configuration 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 information 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) or gigabytes (G), for example `512M` or `1g`.
format (Optional)	body	string	Format of disk, can be `ext2`, `ext3`, `ext4`, `swap`, `xfs`, `none`. The file system `none` means that there is no need to create a file system, and in turn no format and partition table will be created, this is usually used for some systems such as z/OS.
is_boot_disk (Optional)	body	boolean	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.5. 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 information.
disk_list	body	list	A list of additional disks information 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, Feilong will use the next vdev of `CONF.zvm.user_root_vdev` as the additional disk’s vdev. For example, if `CONF.zvm.user_root_vdev` is 0100, Feilong will use 0101 as the vdev for first additional disk in disk_info, and 0102 as the second additional disk’s vdev.
format	body	string	Format of disk, can be `ext2`, `ext3`, `ext4`, `swap`, `xfs`, `none`. The file system `none` means that there is no need to create a file system, and in turn no format and partition table will be created, this is usually used for some systems such as z/OS.
mntdir (Optional)	body	string	The directory on guest to which the additional disk will be mounted. If not specified, Feilong will use `/mnt/ephemeral0` as the mount point of first additional disk, and `/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.6. Guest delete disks¶

DELETE /guests/{userid}/disks

Delete disks from a guest 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 contains the vdevs tor 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.7. Attach volume¶

POST /guests/volumes

Attach a volume to a VM in z/VM.

Request:

Name	In	Type	Description
info	body	dict	A dict to describe connection information of the volume.
connection	body	dict	A dict to describe information 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.
fcp_template_id	body	string	FCP template identifier.
target_wwpn	body	list	World Wide Port Numbers, must start with `0x`, for example `0x50050763050b073d`.
target_lun	body	string	Logical Unit Number, must start with `0x`, for example `0x4020400100000000`.
os_version	body	string	Operating system version. The valid values are: `rhel6.x`, `rhel7.x`, `rhel8.x`, `rhel9.x`, `sles11.x`, `sles12.x`, `sles15.x`, `ubuntu16.x`, `ubuntu20.x`, `ubuntu22.x`, and `rhcos4.x`, all case insensitive. Please contact your cloud administrator if you don’t know the guest’s OS version.
multipath	body	boolean	Multipath service is open or not.
mount_point (Optional)	body	string	The symbolic link name of the volume device. If not assigned, will be assigned by the OS in VM.
is_root_volume (Optional)	body	boolean	Volume is bootable or not.
do_rollback (Optional)	body	boolean	Roll back will be done if any phase fails. Default is True.

Request sample:

{
  "info":
  {
      "connection":
      {
        "assigner_id": "username",
        "zvm_fcp": ["1fc5"],
        "fcp_template_id": "307c88c6-a5e0-11ef-b1eb-5b75c5890e27",
        "target_wwpn": ["0x50050763050b073d"],
        "target_lun": "0x4020400100000000",
        "os_version": "redhat7",
        "multipath": True,
        "mount_point": "/dev/sdz",
        "is_root_volume": False,
        "do_rollback": True
      }
  }
}

Response code:

HTTP status code 200 on success.
Response contents:

No Response
Note:

If multipath is requested, multipath software must be installed on the guest, and multipathd service must be running, for this method to work.

7.5.8. Detach volume¶

DELETE /guests/volumes

Detach a volume from a VM in z/VM.

Request:

Name	In	Type	Description
info	body	dict	A dict to describe connection information of the volume.
connection	body	dict	A dict to describe information 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	list	World Wide Port Numbers, must start with `0x`, for example `0x50050763050b073d`.
target_lun	body	string	Logical Unit Number, must start with `0x`, for example `0x4020400100000000`.
os_version	body	string	Operating system version. The valid values are: `rhel6.x`, `rhel7.x`, `rhel8.x`, `rhel9.x`, `sles11.x`, `sles12.x`, `sles15.x`, `ubuntu16.x`, `ubuntu20.x`, `ubuntu22.x`, and `rhcos4.x`, all case insensitive. Please contact your cloud administrator if you don’t know the guest’s OS version.
multipath	body	boolean	Multipath service is open or not.
mount_point (Optional)	body	string	The symbolic link name of the volume device. If not assigned, will be assigned by the OS in VM.
is_root_volume (Optional)	body	boolean	Volume is bootable or not.
update_connections_only (Optional)	body	boolean	Update connections in database only, do not undedicate in CP.
do_rollback (Optional)	body	boolean	Roll back will be done if any phase fails. Default is True.

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,
        "update_connections_only": False,
        "do_rollback": True
      }
  }
}

Response code:

HTTP status code 200 on success.
Response contents:

No Response

7.5.9. Get guests stats including CPU and memory¶

GET /guests/stats

Get guests CPU and memory information.

Request:

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

Response code:

HTTP status code 200 on success.
Response contents:

Name	In	Type	Description
output	body	dict	CPU and memory statistics of guests, as a dictionary where the key is the userid and the value is the CPU and memory statistics.
guest_cpus	body	integer	The count of virtual CPUs for the guest.
used_cpu_time_us	body	integer	The CPU time used in microseconds.
elapsed_cpu_time_us	body	integer	The CPU time elapsed in microseconds.
min_cpu_count	body	integer	The minimal count of virtual CPUs allowed.
max_cpu_limit	body	integer	The maximal count of virtual CPUs allowed.
samples_cpu_in_use	body	integer	Samples CPU in use.
samples_cpu_delay	body	integer	Samples CPU delay.
used_mem_kb	body	integer	Memory size used by the guest, in kilobytes.
max_mem_kb	body	integer	The maximum memory in kilobytes that can be allocated for this guest.
min_mem_kb	body	integer	The maximum memory in kilobytes that can be allocated for this guest.
shared_mem_kb	body	integer	Shared memory in kilobytes.
total_memory	body	integer	Total memory.
available_memory	body	integer	Available memory.
free_memory	body	integer	Free memory.

Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": {
        "MYGUEST": {
            "guest_cpus": 2,
            "used_cpu_time_us": 509530870,
            "elapsed_cpu_time_us": 260788896874,
            "min_cpu_count": 2,
            "max_cpu_limit": 10000,
            "samples_cpu_in_use": 335,
            "samples_cpu_delay": 116,
            "used_mem_kb": 396232,
            "max_mem_kb": 2097152,
            "min_mem_kb": 0,
            "shared_mem_kb": 396232,
            "total_memory": 2030428,
            "available_memory": 892136,
            "free_memory": 791368
        }
    }
}

7.5.10. Get guests interface stats¶

GET /guests/interfacestats

Get guests network interface statistics.

Request:

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

Response code:

HTTP status code 200 on success.
Response contents:

Name	In	Type	Description
output	body	dict	vNIC statistics of guests, as a dictionary where the key is the userid and the value is a list of vNIC statistics.
vswitch_name (Optional)	path	string	vswitch name.
nic_vdev	body	string	The device number of the NIC.
nic_fr_rx	body	integer	Number of received frames.
nic_fr_tx	body	integer	Number of transmitted frames.
nic_fr_rx_dsc	body	integer	Number of received frames that have been discarded.
nic_fr_tx_dsc	body	integer	Number of transmitted frames that have been discarded.
nic_fr_rx_err	body	integer	Number of received frames that were in error.
nic_fr_tx_err	body	integer	Number of transmitted frames that were in error.
nic_rx	body	integer	Number of received bytes.
nic_tx	body	integer	Number of transmitted bytes.

Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": {
        "MYGUEST": [
            {
                "vswitch_name": "MYSWITCH",
                "nic_vdev": "1000",
                "nic_fr_rx": 116686,
                "nic_fr_tx": 14892,
                "nic_fr_rx_dsc": 0,
                "nic_fr_tx_dsc": 0,
                "nic_fr_rx_err": 0,
                "nic_fr_tx_err": 0,
                "nic_rx": 6131168,
                "nic_tx": 1367740
            }
        ]
    }
}

7.5.11. 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 identifier.
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.12. Show guest definition¶

GET /guests/{userid}

Display the user direct for 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 with only one entry describing user directory.

Response sample:

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

7.5.13. 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.14. 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.15. 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 kilobytes that 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	Memory size used by the guest, in kilobytes.
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.16. 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 with only one entry describing user directory.

Response sample:

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

7.5.17. 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 information for the guest. It has one or more dictionaries that contain some of the below keys. One dictionary represents one 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 directory. Format should be xx:xx:xx:xx:xx:xx, where 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.18. 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 directory. Format should be xx:xx:xx:xx:xx:xx, where x is a hexadecimal digit.
active (Optional)	body	boolean	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.19. 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 values are: `rhel6.x`, `rhel7.x`, `rhel8.x`, `rhel9.x`, `sles11.x`, `sles12.x`, `sles15.x`, `ubuntu16.x`, `ubuntu20.x`, `ubuntu22.x`, and `rhcos4.x`, all case insensitive. Please contact your cloud administrator if you don’t know the guest’s OS version.
guest_networks	body	list	Network information 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 servers address 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`: host name
active (Optional)	body	boolean	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.20. Delete network interface¶

DELETE /guests/{userid}/interface

Delete a network interface on given 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 values are: `rhel6.x`, `rhel7.x`, `rhel8.x`, `rhel9.x`, `sles11.x`, `sles12.x`, `sles15.x`, `ubuntu16.x`, `ubuntu20.x`, `ubuntu22.x`, and `rhcos4.x`, all case insensitive. Please contact 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	boolean	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.21. 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.22. 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.23. Softstop guest¶

Stop a guest gracefully, it will first shut down the OS on the 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.24. 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.25. 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.26. 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.27. 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.28. 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.29. 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.30. 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.31. 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.32. 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.33. 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.34. 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 to 4 digits suffixed by either M (megabytes) or G (gigabytes). The number should be an integer, e.g. 512M or 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. For example, the following configuration would define the default maximum memory size as 64G.
```
[zvm]
user_default_max_memory=64g
```

7.5.35. 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 to 4 digits suffixed by either M (megabytes) or G (gigabytes). The number should be an integer, e.g. 512M or 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.36. Deploy guest¶

POST /guests/{userid}/action

After guest is 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 is required and should be the ignition file.
remotehost (Optional)	body	string	The server where the transportfiles is located. If remotehost is not specified, Feilong 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 e.g.``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` is 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.37. 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.38. 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 values are: `rhel6.x`, `rhel7.x`, `rhel8.x`, `rhel9.x`, `sles11.x`, `sles12.x`, `sles15.x`, `ubuntu16.x`, `ubuntu20.x`, `ubuntu22.x`, and `rhcos4.x`, all case insensitive. Please contact 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.39. 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.40. 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 information used to describe the couple/uncouple action.
couple	body	boolean	couple or uncouple action.
active (Optional)	body	boolean	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.41. Delete guest NIC¶

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

Delete a NIC on the guest.

Request:

Name	In	Type	Description
userid	path	string	Guest userid.
vdev	path	string	NIC device number, 1 to 4 hexadecimal digits.
active (Optional)	body	boolean	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 and information from the host (hypervisor) they are 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	integer	The total available size of the disks in the pool in Gigabytes(G).
disk_total	body	integer	The total size of the pool in Gigabytes (G).
disk_used	body	integer	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 disk pool.

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	integer	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 information for a 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 values are: `rhel6.x`, `rhel7.x`, `rhel8.x`, `rhel9.x`, `sles11.x`, `sles12.x`, `sles15.x`, `ubuntu16.x`, `ubuntu20.x`, `ubuntu22.x`, and `rhcos4.x`, all case insensitive. Please contact 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, e.g. `3338:CYL` or `614200:BLK`.
image_size_in_bytes	body	string	Physical image size in bytes, e.g. `5120000`.
type	body	string	How the image is generated, if it is 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 is 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 information 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. The image can be imported from 3 types of locations: local file system, e.g. `file:///opt/images/import.img`. HTTP server, e.g. `http://192.168.2.1/path/to/import.img` file system on remote host: in this case both url and remote_host parameters should be specified.
image_meta	body	dict	The metadata that describes the image. The valid keys are os_version, md5sum, and disk_type. os_version is a required key, the valid values are: `rhel6.x`, `rhel7.x`, `rhel8.x`, `rhel9.x`, `sles11.x`, `sles12.x`, `sles15.x`, `ubuntu16.x`, `ubuntu20.x`, `ubuntu22.x`, and `rhcos4.x`, all case insensitive. Please contact 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 imported. If remote_host is None, the image will be imported 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 information of the image to be exported.
dest_url	body	string	The location of the exported image. The image can be exported to 2 types of locations: local file system, e.g. `file:///opt/images/export.img` file system on remote host: in this case both dest_url and remote_host parameters 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 e.g.``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 information after it has been exported.

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, e.g. `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(es)¶

Management of virtual switches.

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 an userid or `*` to specify 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 the switch, `IP` or `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 to create the vswitch in the permanent configuration of 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 information 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	body	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	body	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 VLAN id 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 VLAN id.
userid	body	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.8.8. Get vswitch info¶

GET /vswitch

Get vswitch information based on port id. Returns one entry per connected NIC.

Request:

Name	In	Type	Description
portid	body	string	The ID of the port.

Response code:

HTTP status code 200 on success.
Response contents:

Name	In	Type	Description
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	The ID of the port.
comments	body	string	The comments for the NIC.

Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": [
                {
                  "userid": "TEST0045",
                  "interface": "4000",
                  "switch": "VSTEST",
                  "port": "da19c4b3-905b-4844-898e-e36813be796e",
                  "comments": ""
                }
              ]
}

7.9. Volume(s)¶

Handling of volumes and FCP devices.

7.9.1. Refresh volume bootmap info¶

PUT /volumes/volume_refresh_bootmap

Refresh a volume’s bootmap info.

Request:

Name	In	Type	Description
fcpchannel	body	list	FCP devices list.
wwpn	body	list	World Wide Port Name identifiers.
lun	body	string	Logical Unit Number identifier.
transportfiles (Optional)	body	string	The files path that used to customize the VM. For RHCOS image, the transportfiles is required and should be the ignition file.
guest_networks (Optional)	body	list	Required only if refresh volume bootmap for RHCOS. Network information 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 servers address 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 sample:

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

7.9.2. Get volume connector¶

GET /volumes/conn/{userid}

Get volume connector for a given userid.

Request:

Name	In	Type	Description
userid	path	string	Guest userid.
reserve	body	boolean	Whether or not reserve the FCP devices.
fcp_template_id	body	string	FCP template identifier.
storage_provider	body	string	Storage provider.
pchid_info	body	dict	Information on physical channel identifier.

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.9.3. Create FCP template¶

POST /volumes/fcptemplates

Create a FCP multipath template.

Request:

Name	In	Type	Description
name	body	string	Name of FCP template.
description (Optional)	body	string	Description of FCP template, e.g. “Two paths template”.
fcp_devices (Optional)	body	string	FCP devices list. ‘-’ indicates a range, and ‘;’ is a separator. Example: “0011-0013;0015;0017-0018”.
host_default (Optional)	body	boolean	This template is the default template for the host or not.
storage_providers (Optional)	body	list	List of storage providers.
min_fcp_paths_count (Optional)	body	integer	Minimum number of multipath paths.

Response code:

HTTP status code 200 on success.
Response contents:

Name	In	Type	Description
fcp_template	body	dict	Various attibutes of the FCP template.
id	body	string	FCP template identifier.
name	body	string	Name of FCP template.
description	body	string	Description of FCP template, e.g. “Two paths template”.
host_default	body	boolean	This template is the default template for the host or not.
storage_providers	body	list	List of storage providers.
min_fcp_paths_count	body	integer	Minimum number of multipath paths.

7.9.4. Delete FCP template¶

DELETE /volumes/fcptemplates/{template_id}

Delete a FCP multipath template.

Request:

Name	In	Type	Description
template_id	path	string	FCP template identifier.

Response code:

HTTP status code 200 on success.
Response contents:

No response.

7.9.5. Get FCP templates¶

GET /volumes/fcptemplates

Get a list of FCP templates.

Request:

Name	In	Type	Description
template_id_list (Optional)	parameter	list	Restrict output to some FCP template ids. If omitted, no restriction on template ids.
assigner_id (Optional)	parameter	string	Restrict output to some userids. If omitted, no restriction on userids.
default_sp_list (Optional)	parameter	string	Restrict output to the storage providers for which this is the default template. If omitted, no restriction on storage providers.
host_default (Optional)	parameter	string	Restrict output to the hosts for which this is the default template. If omitted, no restriction on hosts.

Request sample:

https://<feilong_fqdn>/volumes/fcptemplates?template_id_list=[
  "45c1d1be-a437-11ef-be87-e1b40fa110c4","4982739c-a457-11ef-be87-e1b40fa110c4"]

Response code:

HTTP status code 200 on success.
Response contents:

Name	In	Type	Description
name	body	string	Name of FCP template.
id	body	string	FCP template identifier.
description	body	string	Description of FCP template, e.g. “Two paths template”.
host_default	body	boolean	This template is the default template for the host or not.
sp_default	body	list	List of storage providers for which this is the default.
min_fcp_paths_count	body	integer	Minimum number of multipath paths.
cpc_sn	body	string	Central Processor Complex serial number.
cpc_name	body	string	Central Processor Complex name.
lpar	body	string	Logical Partition.
hypervisor_hostname	body	string	Name of z/VM hypervisor.
pchids	body	list	Physical Channel identifiers.

7.9.6. Edit FCP template¶

PUT /volumes/fcptemplates/{template_id}

Change some values in an existing FCP template.

Request:

Name	In	Type	Description
template_id	path	string	FCP template identifier.
name (Optional)	body	string	Name of FCP template.
description (Optional)	body	string	Description of FCP template, e.g. “Two paths template”.
fcp_devices (Optional)	body	string	FCP devices list. ‘-’ indicates a range, and ‘;’ is a separator. Example: “0011-0013;0015;0017-0018”.
host_default (Optional)	body	boolean	This template is the default template for the host or not.
default_sp_list (Optional)	body	list	List of storage providers for which this template is the default.
min_fcp_paths_count (Optional)	body	integer	Minimum number of multipath paths.

Response code:

HTTP status code 200 on success.
Response contents:

No response.

7.9.7. Get FCP templates details¶

GET /volumes/fcptemplates/detail

Get more information about FCP templates, including raw data and/or statistics.

Request:

Name	In	Type	Description
template_id_list (Optional)	parameter	list	Restrict output to some FCP template ids. If omitted, no restriction on template ids.
raw (Optional)	parameter	boolean	Whether to get raw FCP usage data from backend or not.
statistics (Optional)	parameter	boolean	Whether to get statistics FCP usage data from backend.
sync_with_zvm (Optional)	parameter	boolean	Whether to sync status of FCP devices with z/VM or not.

Request sample:

https://<feilong_fqdn>/volumes/fcptemplates?template_id_list=[
  "45c1d1be-a437-11ef-be87-e1b40fa110c4","4982739c-a457-11ef-be87-e1b40fa110c4"]&
  statistics=true

Response code:

HTTP status code 200 on success.
Response contents:

Name	In	Type	Description
id	body	string	FCP template identifier.
name	body	string	Name of FCP template.
description	body	string	Description of FCP template, e.g. “Two paths template”.
host_default	body	boolean	This template is the default template for the host or not.
storage_providers	body	list	List of storage providers.
min_fcp_paths_count	body	integer	Minimum number of multipath paths.
raw (Optional)	body	dict	For each FCP, provides raw data, if it was requested.
statistics (Optional)	body	dict	For each FCP, provides the following statistics, if it was requested: `total`, `total_count`, `single_fcp`, `range_fcp`, `available`, `available_count`, `allocated`, `reserve_only`, `connection_only`, `unallocated_but_active`, `allocated_but_free`, `notfound`, `offline`, `chids`, and `pchids`.
cpc_sn	body	string	Central Processor Complex serial number.
cpc_name	body	string	Central Processor Complex name.
lpar	body	string	Logical Partition.
hypervisor_hostname	body	string	Name of z/VM hypervisor.
pchids	body	list	Physical Channel identifiers.

7.9.8. 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	FCP Device number, for example `1fc5`.

Response code:

HTTP status code 200 on success.
Response contents:

Name

In

Type

Description

output

body

list

FCP usage, as a list with 4 entries:

the userid this FCP belongs to
0 or 1, represents whether the FCP is being used or not
the count of volumes on this FCP
the FCP template id used to create this FCP

Response sample:

{
    "rs": 0,
    "overallRC": 0,
    "modID": null,
    "rc": 0,
    "errmsg": "",
    "output": ["testid", 1, 3, "065597ea-a818-11ef-b692-023afc00002f"]
}

7.9.9. 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	FCP Device number, for example `1fc5`.
userid	body	string	Guest userid.
reserved	body	integer	If value is 1, means this FCP device is used by an userid. If value is 0, means this FCP device can be operated.
connections	body	integer	The count of volumes on this FCP device.
fcp_template_id	body	string	FCP template identifier.

Response code:

HTTP status code 200 on success.
Response contents:

No response.

7.10. Files¶

Imports and exports raw file data.

These operations may be restricted to Feilong administrators.

7.10.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 it has been imported into Feilong. For example, `file:///var/lib/zvmsdk/files/imported/be919b98-8408-11e8-b9fe-020001000053`.
filesize_in_bytes	body	integer	The physical file size in bytes.
md5sum	body	string	The md5sum of the file after it has been 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.10.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, e.g. `/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.