' + + '' + + _("Hide Search Matches") + + "
" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/doc/html/architecture.html b/doc/html/architecture.html new file mode 100644 index 000000000..3fa43268f --- /dev/null +++ b/doc/html/architecture.html @@ -0,0 +1,138 @@ + + + + + + + +Feilong is a Software Development Kit (SDK) for managing z/VM resources. +It provides a set of APIs to operate these resources, including guest, image, +network, volume etc. It comes with a python client library, +but can be used from other languages.
+Example 1: integration with OpenStack
+Here is an internal component list of Feilong:
+
+New features released with zVMCLoudConnector 1.4.0:
+Attach/detach volume to inactive guest.
Support set hostname without cloud-init.
New features released with zVMCloudConnector 1.3.0:
+Support upload image through octet stream.
Guest live migrate, support live migrate in z/VM SSI cluster.
Live resize guest memory, and static resize guest memory.
Attach/detach volume to active guest.
zVMCloudConnector 1.2.1 includes one change:
+Support “application/json,utf-8” context type in restclient.
Following new features released with zVMCloudConnector 1.2.0:
+Dedicate OSA device to guest. If osa_device specified when invoking +z/VM Cloud Connector restful API to create network interface, the OSA device +will be dedicated to the guest.
Resize CPUs of guest. Resize guest CPU count by updating static definition.
Live resize CPUs of guest. Currently only increasing CPU count is supported, +decreasing is not supported.
zVMCloudConnector 1.1.0 is mainly includes the change:
+Switch config drive format from tgz to iso9660
+++Config drive in iso9660 format is commonly used by cloud-init.
+
zVMCloudConnector 1.0.1 release mainly adapts to the SMAPI changes in z/VM 6.4 +APAR VM66120 1Q 2018. If the z/VM 6.4 has been applied APAR VM66120, must +upgrade z/VM Cloud Connector to 1.0.1 .
+zVMCloudConnector 1.0.0 release includes many basic features that enables +z/VM Cloud management through zVMCloudConnector APIs.
+Supported features
+Host(hypervisor) management
+get host information and get host disk pool information.
+Guests(virtual machines) management
+Provisoning: create, delete guest definition; capture, deploy guests; +create, delete, configure disks; create, delete, couple, uncouple vnics to +vswitch; configure vnics and network interfaces.
Power actions including start, stop, softstop, reboot, reset, pause, +unpause and get power state.
Query information: get guest information, guest list, get guest definition +information, get console outputs, get nic information.
Image management
+Support import, export, delete images; query image information, get image +root disk size.
+Network features
+vswitch: create, delete vswitch; grant, revoke vswitch access, +get vswitch list, query vswitch information, set user vlan id.
Hot plug/unplug network interfaces to live guest.
Monitoring
+Inspect virtual machine cpu, memory and vnic stats.
+RESTful API
+zVMCloudConnector provides standard RESTful API, which makes it easier to +integrate with other cloud platforms. zVMCloudConnector RESTful API supports +to be configured in a HTTP or HTTPS server.
+Authorization mechanism
+Support token based validation mechanism to make sure all zVMCloudConnector +RESTful API requests are authorized.
+IUCV management channel
+zVMCloudConnector manages virtual machines through z/VM IUCV communication +channel, which does not require network connection.
+Monitoring data cache
+Implement a cache layer in zVMCloudConnector to improve performance of getting +monitoring data.
+Beta release since Dec 4, 2017
+[database]
+
+#
+# Directory to store database.
+#
+# SDK databases are used to store a set of tables which contain the
+# information of network, volume, image, etc. This option is used to
+# tell SDK where to store the database files, make sure the process
+# running SDK is able to read write and execute the directory.
+#
+# This param is optional
+#dir=/var/lib/zvmsdk/databases/
+
+
+[file]
+
+#
+# Directory to store sdk imported or exported files.
+#
+# SDK file repository to store the imported files and the files that will be
+# exported, the imported files will be put into <file_repository>/imported
+# the files to be exported will be put into <file_repository>/exported
+#
+# This param is optional
+#file_repository=/var/lib/zvmsdk/files
+
+
+[guest]
+
+#
+# The maximum allowed console log size, in kilobytes.
+#
+# Console logs might be transferred to sdk user, this option controls how
+# large each file can be. A smaller size may mean more calls will be needed
+# to transfer large consoles, which may not be desirable for performance reasons.
+#
+# This param is optional
+#console_log_size=100
+
+
+#
+# Whether to automatically extend the partition and filesystem of guest.
+#
+# If set to True, when deploying an image to a larger disk, zvmsdk
+# automatically extends the last partition and the file system to
+# use up the whole disk.
+#
+# If do not want to do the extend action automaictly, you must set this option
+# to be False.
+#
+# This param is optional
+#extend_partition_fs=True
+
+
+#
+# The maximum time waiting until the guest reachable after started.
+#
+# When starting a guest, specify the timeout value will check the guest status
+# until it becomes reachable or timeout.
+#
+# This param is optional
+#reachable_timeout=180
+
+
+#
+# The interval time between 2 retries, in seconds.
+#
+# This will take effect only when you set softstop_retries item.
+# What's more, the value of softstop_timeout/softstop_interval is
+# the times retried.
+#
+# This param is optional
+#softstop_interval=10
+
+
+#
+# The maximum time waiting until the guest shut down.
+#
+# Sometimes, the shutdown action will take a bit lone time to complete.
+# If you want to make sure the guest in shut-down status after executing action
+# of softstop, this will help.
+#
+# This param is optional
+#softstop_timeout=120
+
+
+[image]
+
+#
+# Default compress level for captured image.
+#
+# This param is optional
+#default_compress_level=6
+
+
+#
+# Directory to store sdk images.
+#
+# SDK image repository to store the imported images and the staging images that
+# is in snapshotting. Once snapshot finished, the image will be removed to the
+# netboot directory accordingly. Two kinds of image repository looks like:
+# /var/lib/zvmsdk/images/netboot/<image_osversion>/<imagename>
+# /var/lib/zvmsdk/images/staging/<image_osversion>/<imagename>
+#
+# This param is optional
+#sdk_image_repository=/var/lib/zvmsdk/images
+
+
+[logging]
+
+#
+# Directory where log file to be put into.
+#
+# SDK has a set of logs to help administrator to debug
+# and audit actions performed through SDK. Edit this option
+# if you want to put logs into specified place.
+#
+# Please ensure the service running on the consume which
+# consumes SDK has the authorization to write to the path.
+#
+# This param is optional
+#log_dir=/var/log/zvmsdk/
+
+
+#
+# Level of the log.
+#
+# SDK utilize python logging package to help admin debug
+# or analyze issues. it's recommend to set this value
+# to logging.DEBUG to get more detailed logs and set it to
+# logging.INFO(default) in normal situation.
+#
+# recommend values:
+# logging.ERROR: level above ERROR will be written to log file.
+# logging.WARNINS: level above WARNING(ERROR, WARNING)
+# will be written to log file.
+# logging.INFO: level above INFO(ERROR, WARNING, INFO)
+# will be written to log file.
+# logging.DEBUG: All log level (ERROR, WARNING, INFO, DEBUG)
+# will be written to log file.
+#
+# This param is optional
+#log_level=logging.INFO
+
+
+[monitor]
+
+#
+# Cached monitor data update interval
+#
+# This is used to prevent excessive effort spent retrieving the
+# monitor data by calling the SDK backend utilities. When this cache
+# is enabled, a inspect call will only call the SDK backend utilities
+# when the inspected guest's info does not exist in the cache or
+# when the cache data is expired. And when an cache update is needed,
+# all the existing guests' data will be retrieved in a single call to
+# the backend.
+#
+# When this value is below or equal to zero, the cache
+# will be disabled and each inspect call will need to call the backend
+# utilities to get the inspected guest's monitor data.
+#
+# This param is optional
+#cache_interval=300
+
+
+[network]
+
+#
+# IP address of the Linux machine which is running SDK on.
+#
+# Some remote copy operations need to be performed during guest creation,
+# this option tell the SDK the host ip which can be used to perform copy
+# from and copy to operations.
+#
+# This param is required
+#my_ip=None
+
+
+[sdkserver]
+
+#
+# The IP address that the SDK server is listening on.
+#
+# When the SDK server deamon starts, it will try to bind to
+# this address and port bind_port, and wait for the SDK client
+# connection to handle API request.
+#
+# This param is optional
+#bind_addr=127.0.0.1
+
+
+#
+# The port that the SDK server is listening on.
+#
+# This will work as a pair with bind_addr when the SDK server daemon
+# starts, more info can be found in that configuration description.
+#
+# This param is optional
+#bind_port=2000
+
+
+#
+# The maximum number of worker thread in SDK server to handle client requests.
+#
+# These worker threads would work concurrently to handle requests from client.
+# This value should be adjusted according to the system resource and workload.
+#
+# This param is optional
+#max_worker_count=64
+
+
+#
+# The size of request queue in SDK server.
+#
+# SDK server maintains a queue to keep all the accepted but not handled requests,
+# and the SDK server workers fetch requests from this queue.
+# To some extent, this queue size decides the max socket opened in SDK server.
+# This value should be adjusted according to the system resource.
+#
+# This param is optional
+#request_queue_size=128
+
+
+[volume]
+
+#
+# fcp pair selection algorithm
+#
+# fcp_list example:
+# fa00-fa02; fb00-fb02
+#
+# If use get_fcp_pair_with_same_index,
+# then fcp pair is randomly selected from below combinations.
+# [fa00,fb00],[fa01,fb01],[fa02,fb02]
+#
+# If use get_fcp_pair,
+# then fcp pair is randomly selected from below combinations.
+# [fa00,fb00],[fa01,fb00],[fa02,fb00]
+# [fa00,fb01],[fa01,fb01],[fa02,fb01]
+# [fa00,fb02],[fa01,fb02],[fa02,fb02]
+#
+# Possible value:
+# 0 : use get_fcp_pair. this is the default
+# 1 : use get_fcp_pair_with_same_index
+#
+# This param is optional
+#get_fcp_pair_with_same_index=0
+
+
+#
+# The timeout value for waiting attach/detach punch scripts
+# execution, in seconds.
+#
+# The default value is 1800 seconds, if the execution of punch scripts
+# reached the timeout, the attach/detach will fail.
+#
+# This param is optional
+#punch_script_execution_timeout=1800
+
+
+#
+# The timeout value for waiting refresh_bootmap execution, in seconds.
+#
+# The default value is 1200 seconds, if the execution of refresh_bootmap
+# reached the timeout, the process of refresh_bootmap will be stopped.
+#
+# This param is optional
+#refresh_bootmap_timeout=1200
+
+
+[wsgi]
+
+#
+# Whether auth will be used.
+#
+# When sending http request from outside to running zvmsdk,
+# Client will be requested to input username/password in order
+# to authorize the call.
+# Set this to 'none' indicated no auth will be used and 'auth'
+# means username and password need to be specified.
+#
+# Possible value:
+# 'none': no auth will be required
+# 'auth': need auth, currently pyjwt is used to return a token
+# to caller if the username and password is correct.
+#
+# This param is optional
+#auth=none
+
+
+#
+# The max total number of concurrent deploy and capture requests allowed in a
+# single z/VM Cloud Connector process.
+#
+# If more requests than this value are revieved concurrently, the z/VM Cloud
+# Connector would reject the requests and return error to avoid resource
+# exhaustion.
+# .
+#
+# This param is optional
+#max_concurrent_deploy_capture=20
+
+
+#
+# file path that contains admin-token to access sdk http server.
+#
+# Admin-token in order to get a user-token from zvm sdk, and the user-token
+# will be used to validate request before user-token expire.
+#
+# This param is optional
+#token_path=/etc/zvmsdk/token.dat
+
+
+#
+# How long the token is valid.
+#
+# If a token auth is used, the token return to user will be
+# expired after the period passed. This ensure an user who
+# get this token will not be authorized all the time, a new
+# token need to be recreated after certain time period.
+#
+# This param is optional
+#token_validation_period=3600
+
+
+[zvm]
+
+#
+# Only used for SMAPIOUT is not ready.
+#
+# This param is optional
+#bypass_smapiout=True
+
+
+#
+# Default LOGONBY userid(s) for the cloud.
+#
+# This is a set of z/VM userid(s) which are allowed to logon using the LOGONBY
+# keyword to the guests created by the z/VM SDK solution, compatible with
+# the LBYONLY keyword of the user directory statement. This value is only used
+# when a guest is created. If you change this value, existing guests' directory
+# entries are not automatically updated with the new value.
+# When an ESM is installed, this parameter only governs when the ESM
+# defers to CP's processing.
+#
+# Usage note:
+# The default is empty string with nothing set.
+# '' is an invalid value and it will cause VM deploying failed.
+# Thus, DO NOT set default_admin_userid=''.
+# When a non-empty string is provided, blank chars will be used as delimiter,
+# you can use LOGONBY xxx command to log on the guest using the corresponding
+# admin userid's password.
+#
+# For example, when you set this value to 'oper1 oper2 oper3 jones', it means
+# you can use any one of 'oper1', 'oper2', 'oper3', 'jones' as an admin user.
+#
+# see the z/VM CP Planning and Administration for additional information.
+#
+# Possible values:
+# A maximum of 8 blank-delimited strings. Each non-blank string must be a
+# valid z/VM userid.
+# e.g 'oper1 oper2' is a valid value.
+# 'o1 o2 o3 o4 o5 o6 o7 o8 o9' is NOT a valid value.
+#
+# This param is optional
+#default_admin_userid=None
+
+
+#
+# Virtual device number for default NIC address.
+#
+# This value is the first NIC virtual device number,
+# each NIC needs 3 numbers for control/read/write, so by default
+# the first NIC's address is 1000, the second one is 1003 etc.
+#
+# Possible values:
+# An integer value in hex format, between 0 and 65536 (x'FFFF').
+# It should not conflict with other device numbers in the z/VM guest's
+# configuration, for example device numbers of the root or ephemeral or
+# persistent disks.
+#
+# Sample NIC definitions in the z/VM user directory:
+# NICDEF 1000 TYPE QDIO LAN SYSTEM <vswitch1> MACID <macid1>
+# NICDEF 1003 TYPE QDIO LAN SYSTEM <vswitch2> MACID <macid2>
+#
+# This param is optional
+#default_nic_vdev=1000
+
+
+#
+# zVM disk pool and type for root/ephemeral disks.
+#
+# The option is combined by 2 parts and use : as separator.
+#
+# The first part is the type of disks in the disk pool.
+# The disks in one disk pool must in same type (ECKD or FBA).
+# Possible values of the disk pool type:
+# A string, either ECKD or FBA.
+#
+# The second part is the volume group name defined in your directory manager
+# on your z/VM system, which will be used for allocating disks for
+# new guest. A dollar sign ($) is not allowed in the name.
+#
+# Sample disk_pool values:
+# ECKD:diskpo1
+# FBA:testpool
+#
+# This param is optional
+#disk_pool=None
+
+
+#
+# Virtual device number for capture function.
+#
+# This value identity the virtual device number for capture
+# image when z/VM guest is power off.
+#
+# Possible values:
+# An string value identify disk number like '0100'.
+# If this value has been configured, capture image function will use
+# this value as disk info to capture with first priority when z/VM
+# guest is power off.
+# This value don't work if z/VM guest status is power on.
+# Sample root disk in user directory:
+# MDISK 0100 <disktype> <start> <end> <volumelabel> <readwrite>
+#
+# This param is optional
+#force_capture_disk=None
+
+
+#
+# The name of a list containing names of virtual servers to be queried. The list
+# which contains the userid list by default is named: VSMWORK1 NAMELIST, see
+# DMSSICNF COPY key: NameListFileIdAny. The list has to be accessible to the
+# SMAPI servers.
+#
+# The length of namelist must no longer than 64.
+#
+# This param is optional
+#namelist=None
+
+
+#
+# The port number of remotehost sshd.
+#
+# This param is optional
+#remotehost_sshd_port=22
+
+
+#
+# The timeout value for a long-duration SMAPI socket is specified in seconds.
+#
+# The default value is 900 seconds.
+#
+# SMAPIs are socket-based systems management application programming interfaces.
+# If the SMAPI socket connection of a long-duration operation exceeds this timeout,
+# the SMAPI long-duration operation will fail.
+#
+# This param is optional
+#smapi_socket_long_call_timeout_seconds=900
+
+
+#
+# The timeout value for a general SMAPI socket is specified in seconds.
+#
+# The default value is 240 seconds.
+#
+# SMAPIs are socket-based systems management application programming interfaces.
+# If the SMAPI socket connection exceeds this timeout, the SMAPI operation will fail.
+#
+# This param is optional
+#smapi_socket_timeout_seconds=240
+
+
+#
+# If configure the dasd group, the user can configure `swap_default_with_mdisk`
+# to create swap device with MDISK or VDISK, the default value `True` means create
+# the swap device with MDISK, if `False`, create the swap device with VDISK.
+#
+# This param is optional
+#swap_default_with_mdisk=True
+
+
+#
+# For swap disk to create from mdisk instead of vdisk only for the below boot from
+# volume case. In boot from volume case, there might be no disk pool at all, then
+# the only choice is to use vdisk (or using FCP LUN which is complicated),
+# if customer doesn't want vdisk, then set this value to `True` so
+# VDISK will not be used and in turn it will fail check. If the customer wants
+# to use MDISK to create swap device, he need configure dasd group and set
+# `swap_default_with_mdisk` to `True` which is the default value.
+#
+# This param is optional
+#swap_force_mdisk=False
+
+
+#
+# The default maximum number of virtual processers the user can define.
+# This value is used as the default value for maximum vcpu number when
+# create a guest with no max_cpu specified.
+#
+# The number must be a decimal value between 1 and 64.
+#
+# This param is optional
+#user_default_max_cpu=32
+
+
+#
+# The default maximum size of memory the user can define.
+# This value is used as the default value for maximum memory size when
+# create a guest with no max_mem specified.
+# The value can be specified by 1-4 bits of number suffixed by either
+# M (Megabytes) or G (Gigabytes) and the number must be a whole number,
+# values such as 4096.8M or 32.5G are not supported.
+#
+# The value should be adjusted based on your system capacity.
+#
+# This param is optional
+#user_default_max_memory=64G
+
+
+#
+# The default maximum size of reserved memory in a vm's direct entry.
+# This value is used as the default value for maximum reserved memory
+# size for a guest.
+# The value can be specified by 1-4 bits of number suffixed by either
+# M (Megabytes) or G (Gigabytes) and the number must be a whole number,
+# values such as 4096.8M or 32.5G are not supported.
+#
+# The value should be adjusted based on your system capacity.
+#
+# This param is optional
+#user_default_max_reserved_memory=64G
+
+
+# This param is optional
+#user_default_password=None
+
+
+#
+# The default SHARE settings configuration.
+#
+# The recommend value of SHARE. From z/VM doc, SHARE is relative value of
+# virtual machine and if you set SHARE to 100 while virtual CPUs are 4,
+# then each vCPU get 25 entitlement.
+#
+# So the mechanism currently is:
+#
+# 1) If a share is given, set SHARE value to the VM
+# 2) If no SHARE is given during creation, check user_default_share_unit
+# 3) If user_default_share_unit is 0, do nothing
+# 4) If user_default_share_unit it not 0(current default is 100),
+# then insert statement `SHARE RELATIVE user_default_share_unit*vCPU`
+# into user direct, for example, with user_default_share_unit=100,
+# 4 vCPU will create `SHARE RELATIVE 400`.
+#
+# This align the best practice of z/VM recommendation.
+#
+# This param is optional
+#user_default_share_unit=100
+
+
+#
+# PROFILE name to use when creating a z/VM guest.
+#
+# When SDK deploys an guest on z/VM, it can include some
+# common statements from a PROFILE definition.
+# This PROFILE must already be included in your z/VM user directory.
+#
+# Possible values:
+# An 8 character name of a PROFILE that is already defined in the z/VM
+# user directory.
+#
+# This param is required
+#user_profile=None
+
+
+#
+# Virtual device number for root disk.
+#
+# When SDK deploys an guest, it creates a root disk and potentially
+# several data disks. This value is the virtual device number of the root
+# disk.
+#
+# Possible values:
+# An integer value in hex format, between 0 and 65536 (x'FFFF').
+# It should not conflict with other device numbers in the z/VM guest's
+# configuration, for example device numbers of the NICs or ephemeral or
+# persistent disks.
+#
+# Sample root disk in user directory:
+# MDISK 0100 <disktype> <start> <end> <volumelabel> <readwrite>
+#
+# This param is optional
+#user_root_vdev=0100
+
+
+This is a reference to Feilong API error codes +and messages.
+overallRC |
+modID |
+rc |
+rs |
+errmsg |
+
|---|---|---|---|---|
Invalid API Input |
++ | + | + | + |
100 |
+400 |
+100 |
+1 |
+Invalid API arg count, API: %(api)s, %(expected)d expected while %(provided)d provided. |
+
100 |
+400 |
+100 |
+2 |
+Invalid API arg type, API: %(api)s, expected types: ‘%(expected)s’, input types: ‘%(inputtypes)s’ |
+
100 |
+400 |
+100 |
+3 |
+Invalid API arg format, error: %(msg)s |
+
100 |
+400 |
+100 |
+4 |
+Missing required option: %(msg)s |
+
Operation on Guest failed |
++ | + | + | + |
300 |
+10 |
+300 |
+1 |
+Database operation failed, error: %(msg)s |
+
300 |
+10 |
+300 |
+2 |
+Failed to add mdisks when creating guest, error: %(msg)s |
+
300 |
+10 |
+300 |
+3 |
+Failed to deploy image to userid: ‘%(userid)s’, unpackdiskimage failed with rc: %(unpack_rc)d, error: %(err)s |
+
300 |
+10 |
+300 |
+4 |
+Failed to deploy image to userid: ‘%(userid)s’, copy configure drive failed: %(err_info)s |
+
300 |
+10 |
+300 |
+5 |
+Failed to capture userid %(userid)s to generate image, error: %(msg)s |
+
300 |
+10 |
+300 |
+6 |
+Failed to resize cpus of guest: ‘%(userid)s’, error: update cpu definition in user entry failed with smt error: ‘%(err)s’. |
+
300 |
+10 |
+300 |
+7 |
+Failed to live resize cpus of guest: ‘%(userid)s’, error: define new cpu to active failed with smt error: ‘%(err)s’. |
+
300 |
+10 |
+300 |
+8 |
+Failed to live resize cpus of guest: ‘%(userid)s’, error: rescan cpus to hot-plug new defined cpus failed: ‘%(err)s’. |
+
300 |
+10 |
+300 |
+9 |
+Failed to resize memory of guest: ‘%(userid)s’, error: lock user entry failed with smt error: ‘%(err)s’. |
+
300 |
+10 |
+300 |
+10 |
+Failed to resize memory of guest: ‘%(userid)s’, error: replace user entry failed with smt error: ‘%(err)s’. |
+
300 |
+10 |
+300 |
+11 |
+Failed to live resize memory of guest: ‘%(userid)s’, error: define standby memory failed with smt error: ‘%(err)s’. |
+
300 |
+10 |
+300 |
+12 |
+Failed to deploy image to userid: ‘%(userid)s’, get unpackdiskimage cmd failed: %(err)s |
+
300 |
+10 |
+300 |
+13 |
+Failed to deploy image to userid: ‘%(userid)s’, ignition file is required when deploying RHCOS image |
+
300 |
+10 |
+300 |
+14 |
+Failed to deploy image to userid: ‘%(userid)s’, %(msg)s |
+
300 |
+10 |
+300 |
+15 |
+Failed to live resize cpus of guest: ‘%(userid)s’, error: enable new defined cpus failed: ‘%(err)s’. |
+
300 |
+10 |
+300 |
+16 |
+Failed to start the guest: ‘%(userid)s’, %(msg)s |
+
300 |
+10 |
+300 |
+17 |
+Failed to live resize memory of guest: ‘%(userid)s’, error: chmem command failed: ‘%(err)s’. |
+
Operation on Network failed |
++ | + | + | + |
300 |
+20 |
+300 |
+1 |
+Database operation failed, error: %(msg)s |
+
300 |
+20 |
+300 |
+2 |
+ZVMSDK network error: %(msg)s |
+
300 |
+20 |
+300 |
+3 |
+Failed to couple nic %(nic)s to vswitch %(vswitch)s on the active guest system, error: %(couple_err)s, and failed to revoke user direct’s changes, error: %(revoke_err)s |
+
300 |
+20 |
+300 |
+4 |
+Failed to create nic %(nic)s for %(userid)s on the active guest system, error: %(create_err)s, and failed to revoke user direct’s changes, error: %(revoke_err)s |
+
300 |
+20 |
+300 |
+5 |
+Failed to actively change network setting for user %(userid)s, error: %(msg)s |
+
Operation on Volume failed |
++ | + | + | + |
300 |
+30 |
+300 |
+1 |
+Database operation failed, error: %(msg)s |
+
300 |
+30 |
+300 |
+3 |
+Volume %(vol)s has already been attached on instance %(inst)s |
+
300 |
+30 |
+300 |
+4 |
+Volume %(vol)s is not attached on instance %(inst)s |
+
300 |
+30 |
+300 |
+5 |
+Refresh bootmap fails, error code: %(errcode)s and reason: %(errmsg)s |
+
300 |
+30 |
+300 |
+6 |
+IUCV failed to get authorization from instance %(userid)s with reason %(msg)s |
+
300 |
+30 |
+300 |
+7 |
+Refresh bootmap timeout with reason %(msg)s |
+
300 |
+30 |
+300 |
+8 |
+Failed to attach volume to instance %(userid)s with reason %(msg)s |
+
300 |
+30 |
+300 |
+9 |
+Failed to detach volume from instance %(userid)s with reason %(msg)s |
+
300 |
+30 |
+300 |
+10 |
+Failed to refresh bootmap for RHCOS: transportfiles are required |
+
300 |
+30 |
+300 |
+11 |
+Failed to get volume connector of %(userid)s: %(msg)s |
+
300 |
+30 |
+300 |
+12 |
+PCHIDs info missing: %(msg)s |
+
Operation on Image failed |
++ | + | + | + |
300 |
+40 |
+300 |
+1 |
+Database operation failed, error: %(msg)s |
+
300 |
+40 |
+300 |
+2 |
+No image schema found for %(schema)s |
+
300 |
+40 |
+300 |
+3 |
+Image import error: Failed to calculate the md5sum of the image |
+
300 |
+40 |
+300 |
+4 |
+Image import error: The md5sum after import is not same as source image, it is possible that the image has been broken during import |
+
300 |
+40 |
+300 |
+5 |
+Image import error: Failed to get the root disk size units of the image via hexdump |
+
300 |
+40 |
+300 |
+6 |
+Image import error: The header of image does not contain built-in disk size units |
+
300 |
+40 |
+300 |
+7 |
+Image import error: The image’s disk type is not valid. Currently only FBA or CKD type image is supported |
+
300 |
+40 |
+300 |
+8 |
+Image import error: Failed to get the physical size of image in bytes |
+
300 |
+40 |
+300 |
+9 |
+Import image from http server failed with reason %(err)s |
+
300 |
+40 |
+300 |
+10 |
+Image import error: Copying image file from remote filesystem failed with error %(err)s |
+
300 |
+40 |
+300 |
+11 |
+The specified remote_host %(rh)s format invalid |
+
300 |
+40 |
+300 |
+12 |
+Import image from local file system failed with error %(err)s |
+
300 |
+40 |
+300 |
+13 |
+Image import error: image name %(img)s already exist in image database |
+
300 |
+40 |
+300 |
+14 |
+Image import error: %(msg)s |
+
300 |
+40 |
+300 |
+20 |
+The image record of %(img)s does not exist |
+
300 |
+40 |
+300 |
+21 |
+Image Export error: Failed to copy image file to remote host with reason: %(msg)s |
+
300 |
+40 |
+300 |
+22 |
+Export image to local file system failed: %(err)s |
+
300 |
+40 |
+300 |
+23 |
+Image file of %(img)s does not exist, so failed to get its timestamp. |
+
Operation on Monitor failed |
++ | + | + | + |
300 |
+50 |
+300 |
+1 |
+Database operation failed, error: %(msg)s |
+
REST API Request error |
++ | + | + | + |
400 |
+120 |
+400 |
+1 |
+Invalid request |
+
The operated object does not exist |
++ | + | + | + |
404 |
+None |
+404 |
+1 |
+%(obj_desc)s does not exist. |
+
404 |
+None |
+404 |
+2 |
+Not found error: ‘%(msg)s’ |
+
404 |
+None |
+404 |
+3 |
+%(obj_desc)s does not exist in directory although it is in DB. The guest could have been deleted out of z/VM Cloud Connector. |
+
The operated object status conflict |
++ | + | + | + |
409 |
+None |
+409 |
+1 |
+Guest ‘%(userid)s’ is not in active status. |
+
409 |
+None |
+409 |
+2 |
+Failed to live resize cpus of guest: ‘%(userid)s’, error: current active cpu count: ‘%(active)i’ is greater than requested count: ‘%(req)i’. |
+
409 |
+None |
+409 |
+3 |
+Failed to resize cpus of guest: ‘%(userid)s’, error: maximum number of cpus is not defined in user directory. |
+
409 |
+None |
+409 |
+4 |
+Failed to resize cpus of guest: ‘%(userid)s’, error: the requested number of cpus: ‘%(req)i’ exceeds the maximum number of cpus allowed: ‘%(max)i’. |
+
409 |
+None |
+409 |
+5 |
+Failed to set vswitch %(vsw)s, error: %(msg)s |
+
409 |
+None |
+409 |
+6 |
+Failed to create nic %(vdev)s for guest %(userid)s, error: %(msg)s |
+
409 |
+None |
+409 |
+7 |
+Failed to create nic %(vdev)s for guest %(userid)s, error: %(obj)s is locked |
+
409 |
+None |
+409 |
+8 |
+Failed to delete nic %(vdev)s for guest %(userid)s, error: %(msg)s |
+
409 |
+None |
+409 |
+9 |
+Failed to delete nic %(vdev)s for guest %(userid)s, error: %(obj)s is locked |
+
409 |
+None |
+409 |
+10 |
+Failed to couple nic %(vdev)s of guest %(userid)s with vswitch %(vsw)s, error: %(msg)s |
+
409 |
+None |
+409 |
+11 |
+Failed to couple nic %(vdev)s of guest %(userid)s with vswitch %(vsw)s, error: %(obj)s is locked |
+
409 |
+None |
+409 |
+12 |
+Failed to uncouple nic %(vdev)s of guest %(userid)s error: %(msg)s |
+
409 |
+None |
+409 |
+13 |
+Failed to uncouple nic %(vdev)s of guest %(userid)s error: %(obj)s is locked |
+
409 |
+None |
+409 |
+14 |
+Failed to dedicate OSA %(osa)s to guest %(userid)s error: %(msg)s |
+
409 |
+None |
+409 |
+15 |
+Failed to dedicate OSA %(osa)s to guest %(userid)s error: %(obj)s is locked |
+
409 |
+None |
+409 |
+16 |
+Failed to delete dedicated device from guest %(userid)s %(vdev)s, error: %(msg)s |
+
409 |
+None |
+409 |
+17 |
+Failed to delete dedicated device from guest %(userid)s %(vdev)s, error: %(obj)s is locked |
+
409 |
+None |
+409 |
+18 |
+Failed to live resize memory of guest: ‘%(userid)s’, error: current active memory size: ‘%(active)i’m is greater than requested size: ‘%(req)i’m. |
+
409 |
+None |
+409 |
+19 |
+Failed to resize memory of guest: ‘%(userid)s’, error: user definition is not in expected format, cann’t get the defined/max/reserved storage. |
+
409 |
+None |
+409 |
+20 |
+Failed to resize memory of guest: ‘%(userid)s’, error: the requested memory size: ‘%(req)im’ exceeds the maximum memory size defined: ‘%(max)im’. |
+
409 |
+None |
+409 |
+21 |
+Failed to live resize memory of guest: %(userid)s, error: the memory size to be increased: ‘%(inc)im’ is greater than the maximum reserved memory size: ‘%(max)im’. |
+
409 |
+None |
+409 |
+22 |
+Failed to delete FCP Multipath Template, error: %(msg)s |
+
409 |
+None |
+409 |
+23 |
+Failed to create or update FCP Multipath Template, error: %(msg)s |
+
409 |
+None |
+409 |
+24 |
+Failed to edit FCP Multipath Template, error: %(msg)s |
+
The operated object is deleted |
++ | + | + | + |
410 |
+None |
+410 |
++ | The operated object is deleted |
+
ZVM SDK Internal Error |
++ | + | + | + |
500 |
+None |
+500 |
+1 |
+Unexpected internal error in ZVM SDK, error: %(msg)s |
+
z/VM Cloud Connector service is unavailable |
++ | + | + | + |
503 |
+120 |
+503 |
+1 |
+Max concurrent deploy/capture requests received, request is rejected. %(req)s |
+
smt errors |
++ | + | + | + |
2 |
+1 |
+2 |
+99 |
+ULTSMP0311E On USERID, command sent through IUCV failed, rc in response string is not an integer. cmd: CMD, rc: RC, out: OUTPUT |
+
2 |
+1 |
+2 |
+99 |
+ULTSMP0312E On USERID, command sent through IUCV failed, reason code in response string is not an integer. cmd: CMD, rc: RC, rs: RS, out: OUTPUT |
+
2 |
+1 |
+1 |
+None |
+ULTSMP0313E On USERID, command sent through IUCV was not authorized or a generic Linux error occurred. cmd: CMD, rc: RC, rs: RS, out: OUTPUT |
+
2 |
+1 |
+2 |
+None |
+ULTSMP0314E IUCV client parameter error sending command to USERID. cmd: CMD, rc: RC, rs: RS, out: OUTPUT |
+
2 |
+1 |
+4 |
+None |
+ULTSMP0315E IUCV socket error sending command to USERID. cmd: CMD, rc: RC, rs: RS, out: OUTPUT |
+
2 |
+1 |
+8 |
+None |
+ULTSMP0316E On USERID, command sent through IUCV failed. cmd: CMD, rc: RC, rs: RS, out: OUTPUT |
+
2 |
+1 |
+16 |
+None |
+ULTSMP0317E File transport failure while processing command for USERID. cmd: CMD, rc: RC, rs: RS, out: OUTPUT |
+
2 |
+1 |
+32 |
+None |
+ULTSMP0318E On USERID, IUCV server file was not found. cmd: CMD, rc: RC, rs: RS, out: OUTPUT |
+
2 |
+1 |
+None |
+None |
+ULTSMP0319E Unrecognized IUCV client error encountered while sending a command through IUCV to USERID. cmd: CMD, rc: RC, rs: RS, out: OUTPUT |
+
3 |
+1 |
+64 |
+None |
+ULTSMP0320E On USERID, command sent through IUCV failed because timeout. cmd: CMD, rc: RC, rs: RS, out: OUTPUT |
+
3 |
+1 |
+415 |
+None |
+ULTGUT0415E Command failed: ‘CMD’, rc: RC out: OUTPUT |
+
4 |
+1 |
+4 |
+1 |
+ULTRQH0001E FUNCTION_NAME SUBFUNCTION_NAME subfunction’s operand at position OPERAND_POSITION (OPERAND) is not an integer: OPERAND_VALUE |
+
4 |
+1 |
+4 |
+2 |
+ULTRQH0002E FUNCTION_NAME’s SUBFUNCTION_NAME subfunction is missing positional operand (OPERAND) at position OPERAND_POSITION. |
+
4 |
+1 |
+4 |
+3 |
+ULTRQH0003E FUNCTION_NAME’s SUBFUNCTION_NAME subfunction KEYWORD keyword operand is missing a value. |
+
4 |
+1 |
+4 |
+4 |
+ULTRQH0004E FUNCTION_NAME’s SUBFUNCTION_NAME subfunction KEYWORD keyword operand is not an integer: KEYWORD_VALUE |
+
4 |
+1 |
+4 |
+5 |
+ULTRQH0005E FUNCTION_NAME’s SUBFUNCTION_NAME subfunction does not recognize keyword: KEYWORD |
+
4 |
+1 |
+4 |
+6 |
+ULTRQH0006E FUNCTION_NAME’s SUBFUNCTION_NAME subfunction encountered an unknown operand: OPERAND |
+
4 |
+1 |
+4 |
+7 |
+ULTRQH0007E Unrecognized function: FUNCTION_NAME |
+
4 |
+1 |
+4 |
+8 |
+ULTRQH0008E Specified function is not ‘HELP’ or ‘VERSION’: SPECIFIED_FUNCTION |
+
4 |
+1 |
+4 |
+9 |
+ULTRQH0009E Too few arguments specified. |
+
4 |
+1 |
+4 |
+10 |
+ULTRQH0010E Userid is missing |
+
4 |
+1 |
+4 |
+11 |
+ULTRQH0011E Subfunction is missing. It should be one of the following: VALID_SUBFUNCTIONS |
+
4 |
+1 |
+4 |
+12 |
+ULTRQH0012E The request data is not one of the supported types of list or string: REQUEST_DATA_TYPE |
+
4 |
+1 |
+4 |
+13 |
+ULTRQH0010E The desired state was: DESIRED_STATS. Valid states are: VALID_STATS |
+
4 |
+1 |
+4 |
+14 |
+ULTRQH0014E The option OPTION1 was specified but the option OPTION2 was not specified. These options must both be specified. |
+
4 |
+1 |
+4 |
+15 |
+ULTRQH0015E The file system was not ‘ext2’, ‘ext3’, ‘ext4’, ‘xfs’ or ‘swap’: FILE_SYSTEM |
+
4 |
+1 |
+4 |
+16 |
+ULTRQH0016E The scp Data Type was not ‘hex’, ‘ebcdic’, or ‘delete’: DATA_TYPE |
+
4 |
+1 |
+4 |
+17 |
+ULTRQH0017W The maxwait time MAX_WAIT sec is not evenly divisible by the poll interval POLL_INTERVAL sec. Maximum wait time will be RECOMMEND_MAX_WAIT sec or RECOMMEND_POLL_INTERVAL poll intervals. |
+
4 |
+1 |
+4 |
+200 |
+ULTGUT0200E The size of the disk is not valid: DISK_SIZE |
+
4 |
+1 |
+4 |
+201 |
+ULTGUT0201E Failed to convert DISK_SIZE to a number of blocks. |
+
4 |
+1 |
+4 |
+202 |
+ULTGUT0202E NUM_BLOCKS is not an integer size of blocks. |
+
4 |
+1 |
+4 |
+203 |
+ULTGUT0203E Failed to convert DISK_SIZE to a number of cylinders. |
+
4 |
+1 |
+4 |
+204 |
+ULTGUT0204E DISK_SIZE is not an integer size of cylinders. |
+
4 |
+1 |
+4 |
+205 |
+ULTMVM0205E memory size did not end with suffix ‘G’ or ‘M’. |
+
4 |
+1 |
+4 |
+206 |
+ULTMVM0206E Max memory size MAX_MEM_SIZE specified is less than initial memory size INIT_MEM_SIZE. |
+
4 |
+1 |
+4 |
+207 |
+ULTMVM0207E VDISK Size (swap disk) is greater than 2G. |
+
4 |
+1 |
+4 |
+400 |
+ULTGUT0400E The worker script SCRIPT_NAME does not exist. |
+
4 |
+1 |
+7 |
+401 |
+ULTGUT0401E Failed to punch FILE_LOCATION file to guest: USERID, out: OUTPUT |
+
4 |
+1 |
+5 |
+402 |
+ULTGUT0402E No information was found for the specified pool(s): DISK_POOL |
+
4 |
+1 |
+99 |
+403 |
+ULTGUT0403E Failed to purge reader file SPOOL_ID, out: OUTPUT |
+
4 |
+1 |
+8 |
+404 |
+ULTGUT0404E Failed to spool the punch to the specified class SPOOL_CLASS, out:OUTPUT |
+
4 |
+1 |
+6 |
+405 |
+ULTGUT0405E Unable to obtain information related to: KEYWORD. Command used was: CMD. Output was: OUTPUT |
+
4 |
+1 |
+9 |
+406 |
+ULTGUT0406E Failed to punch FILE_LOCATION because of VMUR timeout |
+
4 |
+1 |
+4 |
+407 |
+ULTGUT0407W Unable to spool reader to all classes, it is possible that there may be additional console files available that are not listed in the response. Response from CMD is OUTPUT |
+
4 |
+1 |
+4 |
+408 |
+ULTGUT0408E Error getting list of files in the reader to search for logs from user USERID. Response from CMD is OUTPUT |
+
4 |
+1 |
+4 |
+409 |
+ULTGUT0409E Unable to get console log for user USERID. The userid is either: not logged on, not spooling its console, or has not created any console output. Error rc=rs=8 returned from Image_Console_Get. |
+
4 |
+1 |
+4 |
+410 |
+ULTGUT0410E Unable to get console log for user USERID no spool files were found in our reader from this user, it is possible another process has already received them. |
+
4 |
+1 |
+4 |
+411 |
+ULTGUT0411E Unable to receive console output file. Reader not online. /sys/bus/ccw/drivers/vmur/0.0.000c/online = 0 |
+
4 |
+1 |
+4 |
+412 |
+ULTGUT0412E Malformed reply from SMAPI, unable to fill in performance information, exception: EXCEPTION, details: EXCEPTION_DETAILS, Response: OUTPUT |
+
4 |
+1 |
+4 |
+423 |
+ULTGUT0423W Unable to spool reader to all classes, it is possible that there may be additional console files available that are not listed in the response. Command: CMD, exception EXCEPTION, details EXCEPTION_DETAILS. Will attempt to continue processing. |
+
4 |
+1 |
+4 |
+424 |
+ULTGUT0424E Failed to transfer FILE_LOCATION file to guest: USERID, out: OUTPUT |
+
5 |
+1 |
+1 |
+501 |
+ULTGUT0501E Timeout Exception recevied on an attempt to execute a cmd: CMD, exception: EXCEPTION, details: EXCEPTION_DETAILS |
+
8 |
+1 |
+None |
+None |
+ULTSMP0300E SMAPI API failed: API_NAME, overall rc: OVERALLRC, rc: RC, rs: RS, errno: ERRNO, cmd: CMD, out: OUTPUT |
+
25 |
+1 |
+301 |
+0 |
+ULTSMP0301E SMAPI API failed: API_NAME, response header does not have the expected 3 values before the (details) string. cmd: CMD, response header: HEADER, out: OUTPUT |
+
25 |
+1 |
+302 |
+0 |
+ULTSMP0302E SMAPI API failed: API_NAME, word 1 in the response header is not an integer or in the range of expected values. word 1: WORD1, cmd: CMD, response header: HEADER, out: OUTPUT |
+
25 |
+1 |
+303 |
+0 |
+ULTSMP0303E SMAPI API failed: API_NAME, word 2 in the response header is not an integer. word 2: WORD2, cmd: CMD, response header: HEADER, out: OUTPUT |
+
25 |
+1 |
+304 |
+0 |
+ULTSMP0304E SMAPI API failed: API_NAME, word 3 in the response header is not an integer. word 3: WORD3, cmd: CMD, response header: HEADER, out: OUTPUT |
+
99 |
+1 |
+305 |
+0 |
+ULTSMP0305E Exception received on an attempt to communicate with SMAPI, cmd: CMD, exception: EXCEPTION, details: EXCEPTION_DETAILS |
+
99 |
+1 |
+99 |
+413 |
+ULTGUT0413E Userid ‘USERID’ did not enter the expected operating system state of ‘DESIRED_STATE’ in MAX_WAIT seconds. |
+
99 |
+1 |
+99 |
+414 |
+ULTGUT0414E Userid ‘USERID’ did not enter the expected virtual machine state of ‘DESIRED_STATE’ in MAX_WAIT seconds. |
+
99 |
+1 |
+99 |
+416 |
+ULTGUT0416E Command returned a response containing ‘KEYWORD’ but did not have at least NUM words following it. cmd: ‘CMD’, out: ‘OUTPUT’ |
+
99 |
+1 |
+99 |
+417 |
+ULTGUT0417E Command did not return the expected response containing ‘KEYWORD’, cmd: ‘CMD’, out: ‘OUTPUT’ |
+
99 |
+1 |
+99 |
+418 |
+ULTGUT0418E Userid USERID is not logged on to this system. |
+
99 |
+1 |
+99 |
+419 |
+ULTGUT0419E A relocation is not in progress for userid USERID. |
+
99 |
+1 |
+99 |
+420 |
+ULTGUT0420E An error occurred issuing a CMD for userid USERID. Please look up message(s): ERROR_CODE in the CP Messages book for more information. |
+
99 |
+1 |
+421 |
+0 |
+ULTGUT0421E Exception received on an attempt to execute a cmd: CMD, exception: EXCEPTION, details: EXCEPTION_DETAILS |
+
99 |
+1 |
+422 |
+0 |
+ULTGUT0422W Exception received on an attempt to execute a cmd: CMD, exception: EXCEPTION, details: EXCEPTION_DETAILS. Will attempt to continue processing. |
+
client errors |
++ | + | + | + |
101 |
+110 |
+101 |
+1 |
+Request to zVM Cloud Connector failed: %(error)s |
+
101 |
+110 |
+101 |
+2 |
+Token file not found: %(error)s |
+
101 |
+110 |
+101 |
+3 |
+Request to url: %(url)s got unexpected response: status_code: %(status)s, reason: %(reason)s, text: %(text)s |
+
101 |
+110 |
+101 |
+4 |
+Get Token failed: %(error)s |
+
101 |
+110 |
+101 |
+1 |
+Failed to create client socket, error: %(error)s |
+
101 |
+110 |
+101 |
+2 |
+Failed to connect SDK server %(addr)s:%(port)s, error: %(error)s |
+
101 |
+110 |
+101 |
+3 |
+Failed to send all API call data to SDK server, only %(sent)d bytes sent. API call: %(api)s |
+
101 |
+110 |
+101 |
+4 |
+Client receive empty data from SDK server |
+
101 |
+110 |
+101 |
+5 |
+Client got socket error when sending API call to SDK server, error: %(error)s |
+
101 |
+110 |
+101 |
+6 |
+Client got socket error when receiving response from SDK server, error: %(error)s |
+
400 |
+110 |
+400 |
+1 |
+Invalid API name, ‘%(msg)s’ |
+
503 |
+110 |
+503 |
+2 |
+Service is unavailable. reason: %(reason)s, text: %(text)s |
+
This section provides answers to frequent asked questions.
+For NIC address on to be created VM, the default value 1000 is defined by
+Feilong configuration file, generally it is defined by default_nic_vdev
+item of zvm section in /etc/zvmsdk/zvmsdk.conf.
If you want to create a VM with different value, change it to any integer you +want and make sure no conflict to other address then restart the Feilong service.
+Currently, Feilong doesn’t support to set a password for virtual machine +(the definition in user directory), it is designed from a security perspective. +Only the administrator has the authority to logon the virtual machine through x3270 +or PCOM, the common user is only allowed to connect to guest through network +(ssh with id and password)
+Refer to default_admin_userid configuration in zvm section for more detail info.
Feilong (also known as python-zvm-sdk) is a client library written in Python +that interacts with z/VM SMAPI (System management API) of IBM Z or +LinuxONE machines. The goal of this package is to make the z/VM SMAPI easy +to be consumed by upper layer programmers and provide a set of APIs to be +called through RESTful interfaces.
+The z/VM SMAPI is the access point for any external tools to +manage the z/VM running on IBM Z or LinuxONE platform. It supports management of +lifecycle and configuration of various platform resources, such as guest, +CPU, memory, virtual switches, disk storage, and more.
+This documentation applies to version 1.6.7 of the Feilong package (python-zvm-sdk). +You can also see that version in the top left corner of this page.
+The Feilong package (python-zvm-sdk) uses the rules of Semantic Versioning 2.0.0 for +its version.
+In this package, compatibility is always seen from the perspective of the user +of the package. Thus, a backwards compatible new version of this package means +that the user can safely upgrade to that new version without encountering +compatibility issues.
+This package uses the rules of Semantic Versioning 2.0.0 for compatibility +between package versions, and for deprecations.
+Violations of these compatibility rules are described in section +Release Notes.
+Deprecated functionality is marked accordingly in this documentation and in the +Release Notes
+If you encounter any problem with this package, please open a bug against +Feilong issue tracker or ask question Feilong question
+This package is licensed under the Apache 2.0 License.
+
+This documentation is under Creative Commons Attribution 4.0 International License
+This section discusses setting up the Linux on System z(zLinux) that is the +target of the initial image capture, after capturing this zLinux, an image will +be generated, it can be used to import into Feilong’s image +repository or Openstack glance for later deployment.
+These are the requirements for an image to be captured and deployed by Feilong:
+The supported Linux distributions are:
RHEL 6.x
RHEL 7.x
RHEL 8.1
SLES 11.x
SLES 12.x
SELS 15
Ubuntu 16.04
Ubuntu 20.04
Where x is the zLinux’s minor release number
+Note: FBA as root disk type is not supported for RHEL 8.1
+The supported root disk type for capture/deploy are:
FBA
ECKD
NOTE: An image deployed via Feilong must match the disk type +configured by disk_pool in /etc/zvmsdk/zvmsdk.conf, only either FBA or ECKD image +can be deployed in zvmsdk, but not both at the same time. If you wish to switch +image types, you need to change the disk_pool configuration option and restart +sdkserver to make the changes take effect.
+If you capture a zLinux with root disk size greater than 5GB, or if you deploy +an image to an root disk larger than 5G in size, please modify the timeout value +for httpd service to make it work expected. Please refer to Configure Apache +section in this document for reference.
The zLinux that used as the source of the captured image should meet the +following criteria:
+++
+- +
The root file system must not be on a logical volume
- +
The minidisk on which the root file system resides should be a minidisk of +the same type as desired for a subsequent deploy (for example, an ECKD disk +image should be captured for a subsequent deploy to an ECKD disk), and it should +not be a full-pack minidisk, since cylinder 0 on full-pack minidisks is reserved.
- +
If the source image is captured from minidisk with virtual address 0100, it must +be deployed to the virtual address 0100 of target Virtual Machine(VM) , otherwise, the deployed vm +will failed to start up. The root disk’s vdev can be configured with user_root_vdev +option under zvm section in /etc/zvmsdk/zvmsdk.conf. The recommendation vdev of root +disk is 0100, this is also the default value.
- +
The root disk should have a single partition
- +
Feilong only support deploy an image to a disk larger or equal than +the source image’s root disk size , otherwise, it would result in loss of data. +The image’s root disk size can be got by command.
++++hexdump -C -n 64 <image_path> +
Prepare a Linux on z Systems virtual server in the z/VM system. You will +have to make adjustments to the procedures that are documented in the below cook +book in order to keep the resulting virtual server within the bounds of the above +image requirements.
For RHEL6.4 and SLES 11 SP3 installation, see http://www.vm.ibm.com/pubs/redbooks/sg248147/files/24814700.pdf
For RHEL 7 installation, see http://www.redbooks.ibm.com/abstracts/sg248303.html?Open
For SLES 12 installation, see http://www.redbooks.ibm.com/abstracts/sg248890.html?Open
For Ubuntu 16.04 installation, see http://www.redbooks.ibm.com/redbooks/pdfs/sg248354.pdf
Install the mkisofs and openssl modules on it.
Make sure SELinux is disabled and the SSH connection (default port number is 22) +can pass the firewall.
Set UseDNS no in /etc/ssh/sshd_config file in order to improve the inventory +collection efficiency.
For Ubuntu 16.04, you must enable root ssh access. By default, root ssh access +is not enabled.
Feilong manages the deployed VM via IUCV channel. IUCV service +should be configured on zLinux before capture it to make image. Following the below +steps to install and configure IUCV service.
+Logon your BYOL(Bring Your Own Linux, which will be used to represent the Linux +on which the Feilong will be run), and copy the following files +to target VM
+scp -r /opt/zthin/bin/IUCV/ root@<zLinux_ip>:/root/
+Where: <zLinux_ip> is the ip address of zLinux
+Logon zLinux, install and configure IUCV service by commands:
+cd /root/IUCV
+./iucvserverdaemoninstaller.sh -a <auth_userid>
+Where: auth_userid is the userid of the BYOL that can talk to zLinux via +IUCV channel, case insensitive, for example:
+./iucvserverdaemoninstaller.sh -a OPNCLOUD
+Setting the authorized client userid to be: OPNCLOUD
+IUCV server daemon is configured and started successfully
+you may get the detail usage of iucvserverdaemoninstaller.sh by command:
+./iucvserverdaemoninstaller.sh -h
+Logon your BYOL, run a simple command to check the if the iucv +channel is set up correctly by commands:
+/opt/zthin/bin/IUCV/iucvclnt <zLinux_userid> date
+Where: <zLinux_userid> is the userid of zLinux.
+If above commands execute successfully, you may continue to next steps. +Otherwise, stop here and re-check the configuration.
+To do useful work with the user data, the zLinux image must be configured to +run a service that retrieves the user data passed from the Feilong +and then takes some actions based on the contents of that data. This task can +be done by cloud-init.
+For zLinux images that deployed by Feilong, zvmguestconfigure must +be installed and started before cloud-init. +These steps of configuration zvmguestconfigure and cloud-init are described in subsequent sections.
+The zvmguestconfigure script/service must be installed in the zLinux so it +can process the request files transmitted by Feilong to the +reader of the zLinux as a class X file. zvmguestconfigure also act as the bridge +between the zLinux and higher layer of zVM Cloud. Take spawning a VM via Openstack +nova-zvm-driver for example, the image uses cloud-init. +If customer spawn a new VM with some customized data to initialize +the VM via nova boot command. The overall work flow of the customized data is +listed as below:
+Openstack nova-zvm-driver generate the cfgdrive.iso file which is iso9660 format +and with label ‘config-2’, this file is used to customize the target VM
nova-zvm-driver then call Feilong to punch the cfgdrive.iso file to +target VM’s reader
When target VM start up, the installed zvmguestconfigure will download cfgdrive.iso +file and then mount it as loop device
When cloud-init run, it will automatically find the proper configure drive data source
+via command blkid -t TYPE=iso9660 -o device, then consume the data provided
+by cfgdrive.iso to customize the VM
The Feilong supports initiating changes to zLinux while it is shut +down or the virtual machine is logged off. The changes to zLinux are implemented +using zvmguestconfigure that is run when Linux is booted the next time. The steps +of how to install zvmguestconfigure is described in subsequent sections.
+Perform the following steps:
+Log on your BYOL, and copy the zvmguestconfigure script that is located at +<zvmsdk_path>/python-zvm-sdk/tools/share/zvmguestconfigure to your +zLinux, where zvmsdk_path can be found at section z/VM SDK install
Logon on your zLinux, change the script to specify the authorizedSenders in +zvmguestconfigure file. It is recommended that this be set to a list of user IDs +which are allowed to transmit changes to the machine. At a minimum, this list +should include the userid of BYOL, which is usually OPNCLOUD. (It can be set +to ‘*’, which indicates any virtual machine on the same LPAR may +send configuration requests to it)
zvmguestconfigure is configured to run with run level 2, 3 and 5. It is not +configured to run as part of custom run level 4. If that run level is going to +be used, then the # Default-Start: line at the beginning of the file should be +updated to specify run level 4 in addition to the current run levels.
Copy the zvmguestconfigure file to /etc/init.d and make it executable
Add the zvmguestconfigure as a service by issuing:
+chkconfig --add zvmguestconfigure
+Activate the script by issuing:
+chkconfig zvmguestconfigure on
+If you wish to run with custom run level 4, then add 4 to the list of levels:
+chkconfig --level 2345 zvmguestconfigure on
+Verify that you installed the correct version of zvmguestconfigure on the +target machine. Do this by issuing the following service command:
+service zvmguestconfigure version
+zvmguestconfigure version: 1.0
+Verify that zvmguestconfigure on the target machine is configured to handle +requests from the server specified at step 2. Do this by issuing the following +service command:
+service zvmguestconfigure status
+zvmguestconfigure is enabled to accept configuration reader files from: OPNCLOUD
+If zvmguestconfigure is not enabled to accept configuration reader files then verify +that you followed Step 2.
+Perform the following steps:
+Log on your BYOL, and copy the zvmguestconfigure and zvmguestconfigure.service +script that are located at <zvmsdk_path>/python-zvm-sdk/tools/share/ folder +to your zLinux, where zvmsdk_path can be found at the section z/VM SDK install.
Logon on your zLinux, change the script to specify the authorizedSenders in +zvmguestconfigure file. It is recommended that this be set to a list of user IDs +which are allowed to transmit changes to the machine. At a minimum, this list +should include the userid of BYOL, which is usually OPNCLOUD. (It can be set +to ‘*’, which indicates any virtual machine on the same LPAR may send configuration requests to it).
Copy the zvmguestconfigure script to the /usr/bin/ folder and make it executable.
Install the zvmguestconfigure.service in the target zLinux:
If the target Linux machine is RHEL7.x, copy the zvmguestconfigureconf4z.service file to: /lib/systemd/system
If the target Linux machine is SLES12.x and SLES15, copy the zvmguestconfigure.service file to: /usr/lib/systemd/system +and it is recommended that you change the NetworkManager.service to be wicked.service in the zvmguestconfigure.service
Enable the zvmguestconfigure service by issuing:
+systemctl enable zvmguestconfigure.service
+Start the zvmguestconfigure service by issuing:
+systemctl start zvmguestconfigure.service
+Logon your BYOL, and copy the zvmguestconfigure and zvmguestconfigure.service +script that are located at <zvmsdk_path>/python-zvm-sdk/tools/share/zvmguestconfigure +to your zLinux, where zvmsdk_path can be found at the section z/VM SDK install
Logon your zLinux, change the script to specify the authorizedSenders in +zvmguestconfigure file. It is recommended that this be set to a list of user IDs +which are allowed to transmit changes to the machine. At a minimum, this list +should include the userid of BYOL. (It can be set to ‘*’, which indicates any +virtual machine on the same LPAR may send configuration requests to it)
On zLinux, copy the zvmguestconfigure script to the /usr/bin/ folder and make +it executable.
Install the zvmguestconfigure.service in the target Ubuntu machine, tailor the +zvmguestconfigure.service file for an Ubuntu 16.04 image by modifying the file +contents as follows:
+[Unit]
+Description=Activation engine for configuring z/VM when it starts
+Wants=local-fs.target
+After=local-fs.target
+Before=cloud-init-local.service network-pre.target
+[Service]
+Type=oneshot
+ExecStart=/usr/bin/zvmguestconfigure start
+StandardOutput=journal+console
+[Install]
+WantedBy=multi-user.target
+After that, copy the zvmguestconfigure.service file to /lib/systemd/system. If the +target Linux machine is Ubuntu 20.04, copy the zvmguestconfigure.service.ubuntu file +to: /lib/systemd/system, and rename to zvmguestconfigure.service.
+Enable the zvmguestconfigure service by issuing:
+systemctl enable zvmguestconfigure.service
+Start the zvmguestconfigure service by issuing:
+systemctl start zvmguestconfigure.service
+Please note that if customer won’t pass customize data via openstack configdrive, +cloud-init will not need to be installed. In this case, the steps in this section +can be ignored.
+OpenStack uses cloud-init as its activation engine.Some distributions include +cloud-init either already installed or available to be installed. +If your distribution does not include cloud-init, you can download the code +from https://launchpad.net/cloud-init/+download. After +installation, if you issue the following shell command and no errors occur, +cloud-init is installed correctly.
+cloud-init init --local
+Installation and configuration of cloud-init differs among different Linux +distributions, and cloud-init source code may change. This section provides +general information, but you may have to tailor cloud-init to meet the needs +of your Linux distribution. You can find a community-maintained list of +dependencies at http://ibm.biz/cloudinitLoZ.
+The z/VM OpenStack support has been tested with cloud-init 0.7.4 and 0.7.5 for +RHEL6.x and SLES11.x, 0.7.6 for RHEL7.x and SLES12.x, and 18.4 for SLES15, and +18.5 for RHEL8.1, and 0.7.8 for Ubuntu 16.04.
+If you are using a different version of cloud-init, you should change your +specification of the indicated commands accordingly.During cloud-init +installation, some dependency packages may be required. You can use yum/zypper +and python setuptools to easily resolve these dependencies. +See https://pypi.python.org/pypi/setuptools for more information.
+Download the cloud-init tar file from Init scripts for use on cloud images +https://launchpad.net/cloud-init/+download
Using the file cloud-init-0.7.5 as an example, +untar this file by issuing the following command:
+tar -zxvf cloud-init-0.7.5.tar.gz
+Issue the following to install cloud-init:
+cd ./cloud-init-0.7.5
+python setup.py build
+python setup.py install
+cp ./sysvinit/redhat/* /etc/init.d
+Update /etc/init.d/cloud-init-local to ensure that it starts after the +zvmguestconfigure and sshd services. On RHEL 6, change the # Required-Start +line in the ### BEGIN INIT INFO section from:
+### BEGIN INIT INFO
+# Provides: cloud-init-local
+# Required-Start: $local_fs $remote_fs
+# Should-Start: $time
+# Required-Stop:
+to:
+### BEGIN INIT INFO
+# Provides: cloud-init-local
+# Required-Start: $local_fs $remote_fs zvmguestconfigure sshd
+# Should-Start: $time
+# Required-Stop:
+The default configuration file /etc/cloud/cloud.cfg is for ubuntu, not RHEL. +To tailor it for RHEL:
+++
+- +
Replace distro:ubuntu with distro:rhel at around line 79.
- +
Change the default user name, password and gecos as you wish, at around lines 82 to 84
- +
Change the groups tag to remove user groups that are not available for this distribution. +After the change, the groups tag at around line 85 should appear similar to the following: +groups: [adm, audio, cdrom, dialout, floppy, video, dip]
++For more information on how to configure cloud-init, please check the cloud-init documentation +http://cloudinit.readthedocs.org/.
+
Cloud-init will try to add user syslog to group adm. This needs to be +changed. RHEL does not have a syslog user by default, so issue:
+useradd syslog
+Add the cloud-init related service with the following commands:
+chkconfig --add cloud-init-local
+chkconfig --add cloud-init
+chkconfig --add cloud-config
+chkconfig --add cloud-final
+Then start them with the following sequence:
+chkconfig cloud-init-local on
+chkconfig cloud-init on
+chkconfig cloud-config on
+chkconfig cloud-final on
+You can issue ls -l /etc/rc5.d/ | grep -e xcat -e cloud to find the services. +(Make sure that zvmguestconfigure starts before any cloud-init service.)
+lrwxrwxrwx. 1 root root 22 Jun 13 04:39 S50xcatconfinit -> ../init.d/zvmguestconfigure
+lrwxrwxrwx. 1 root root 26 Jun 13 04:39 S51cloud-init-local -> ../init.d/cloud-init-local
+lrwxrwxrwx. 1 root root 20 Jun 13 04:39 S52cloud-init -> ../init.d/cloud-init
+lrwxrwxrwx. 1 root root 22 Jun 13 04:39 S53cloud-config -> ../init.d/cloud-config
+lrwxrwxrwx. 1 root root 21 Jun 13 04:39 S54cloud-final -> ../init.d/cloud-final
+To verify cloud-init configuration, issue: cloud-init init –local
+cloud-init init --local
+Make sure that no errors occur. The following warning messages can be ignored:
+/usr/lib/python2.6/site-packages/Cheetah-2.4.4-py2.6.egg/Cheetah/Compiler.py:1509: UserWarning: +You don’t have the C version of NameMapper installed! I’m disabling Cheetah’s useStackFrames +option as it is painfully slow with the Python version of NameMapper. You should get a copy +of Cheetah with the compiled C version of NameMapper. You don’t have the C version of NameMapper installed!
+Issue following command, if this file exists, or cloud-init will not work after reboot.
+rm -rf /var/lib/cloud
+Download the cloud-init tar file from https://launchpad.net/cloud-init/+download.
Using the file cloud-init-0.7.5 as an example, untar this file by issuing +the following command:
+tar -zxvf cloud-init-0.7.5.tar.gz
+Issue the following commands to install cloud-init:
+cd ./cloud-init-0.7.5
+python setup.py build
+python setup.py install
+NOTE:: After you issue the command tar -zxvf cloud-init-0.7.5.tar.gz, +the directory ./sysvinit/sles/ does not exist. So you have to copy the +cloud-init related services from ./sysvinit/redhat/* to /etc/init.d/:
+cp ./sysvinit/redhat/* /etc/init.d
+You will find that four scripts, cloud-init-local, cloud-init, cloud-config, +and cloud-final are added to /etc/init.d/. Modify each of them by replacing +the variable:
+cloud_init="/usr/bin/cloud-init"
+with:
+cloud_init="/usr/local/bin/cloud-init"
+Update /etc/init.d/cloud-init-local to ensure that it starts after the +zvmguestconfigure service. On SLES, change the # Required-Start line in the +### BEGIN INIT INFO section from:
+### BEGIN INIT INFO
+# Provides: cloud-init-local
+# Required-Start: $local_fs $remote_fs
+# Should-Start: $time
+# Required-Stop:
+to:
+### BEGIN INIT INFO
+# Provides: cloud-init-local
+# Required-Start: $local_fs $remote_fs zvmguestconfigure
+# Should-Start: $time
+# Required-Stop:
+The default configuration file /etc/cloud/cloud.cfg is for ubuntu, not SLES. To tailor it for SLES:
+++
+- +
Replace distro:ubuntu with distro:sles at around line 79.
- +
Change the default user name, password and gecos as you wish, at around lines 82 to 84.
- +
Change the groups at around line 85: groups: [adm, audio, cdrom, dialout, floppy, video, dip]
- +
Cloud-init will try to add user syslog to group adm. This needs to be changed. For SLES, issue the following commands:
+++useradd syslog +groupadd adm +For more information on changing these values, see the cloud-init documentation http://cloudinit.readthedocs.org/
+
Start the cloud-init related services with the following commands, +ignoring the error “insserv: Service network is missed in the runlevels 4 +to use service cloud-init” if it occurs:
+insserv cloud-init-local
+insserv cloud-init
+insserv cloud-config
+insserv cloud-final
+At this point, you should find that the services in /etc/init.d/rcX.d appear as +you would expect (make sure that zvmguestconfigure starts before any cloud-init service):
+lrwxrwxrwx. 1 root root 22 Jun 13 04:39 S50xcatconfinit -> ../init.d/zvmguestconfigure
+lrwxrwxrwx. 1 root root 26 Jun 13 04:39 S51cloud-init-local -> ../init.d/cloud-init-local
+lrwxrwxrwx. 1 root root 20 Jun 13 04:39 S52cloud-init -> ../init.d/cloud-init
+lrwxrwxrwx. 1 root root 22 Jun 13 04:39 S53cloud-config -> ../init.d/cloud-config
+lrwxrwxrwx. 1 root root 21 Jun 13 04:39 S54cloud-final -> ../init.d/cloud-final
+To verify cloud-init configuration, issue:
+cloud-init init --local
+Make sure that no errors occur. The following warning messages can be ignored: +/usr/lib/python2.6/site-packages/Cheetah-2.4.4-py2.6.egg/Cheetah/Compiler.py:1509: +UserWarning: +You don’t have the C version of NameMapper installed! I’m disabling Cheetah’s useStackFrames +option as it is painfully slow with the Python version of NameMapper. You should get a copy +of Cheetah with the compiled C version of NameMapper. +You don’t have the C version of NameMapper installed!
+Issue following command, if this file exists, or cloud-init will not work after reboot.
+rm -rf /var/lib/cloud
+Download cloud-init0.7.6 from https://launchpad.net/cloud-init/+download.
Untar it with this command:
+tar -zxvf cloud-init-0.7.6.tar.gz
+Issue the following commands to install cloud-init:
+cd ./cloud-init-0.7.6
+python setup.py build
+python setup.py install --init-system systemd
+OpenStack on z/VM uses ConfigDrive as the data source during the installation +process. You must add the following lines to the default +configuration file, /etc/cloud/cloud.cfg:
+# Example datasource config
+# datasource:
+# Ec2:
+#
+# metadata_urls: [ ’blah.com’ ]
+#
+# timeout: 5 # (defaults to 50 seconds)
+#
+# max_wait: 10 # (defaults to 120 seconds)
+datasource_list: [ ConfigDrive, None ]
+datasource:
+ ConfigDrive:
+ dsmode: local
+NOTE: please pay attention to the indentation, otherwise, cloud-init may not +work as expected.
+In order to work well with other products, the service start up sequence +for cloud-init-local and cloud-init should be changed to the following. +(The cloud-init related service files are located in the folder +/lib/systemd/system/ for RHEL7.x and in /usr/lib/systemd/system/ for SLES12.x)
+cat /lib/systemd/system/cloud-init-local.service
+[Unit]
+Description=Initial cloud-init job (pre-networking)
+Wants=local-fs.target sshd.service sshd-keygen.service
+After=local-fs.target sshd.service sshd-keygen.service
+[Service]
+Type=oneshot
+ExecStart=/usr/bin/cloud-init init --local
+RemainAfterExit=yes
+TimeoutSec=0
+# Output needs to appear in instance console output
+StandardOutput=journal+console
+[Install]
+WantedBy=multi-user.target
+
+# cat /lib/systemd/system/cloud-init.service
+[Unit]
+Description=Initial cloud-init job (metadata service crawler)
+After=local-fs.target network.target cloud-init-local.service
+Requires=network.target
+Wants=local-fs.target cloud-init-local.service
+[Service]
+Type=oneshot
+ExecStart=/usr/bin/cloud-init init
+RemainAfterExit=yes
+TimeoutSec=0
+# Output needs to appear in instance console output
+StandardOutput=journal+console
+[Install]
+WantedBy=multi-user.target
+Manually create the cloud-init-tmpfiles.conf file:
+touch /etc/tmpfiles.d/cloud-init-tmpfiles.conf
+Insert comments into the file by issuing the following command:
+echo "d /run/cloud-init 0700 root root - -" > /etc/tmpfiles.d/cloud-init-tmpfiles.conf
+Because RHEL does not have a syslog user by default, you have to add it manually:
+useradd syslog
+In /etc/cloud/cloud.cfg, remove the ubuntu-init-switch, growpart and +resizefs modules from the cloud_init_modules section. Here is the +cloud_init_modules section after the change:
+# The modules that run in the ’init’ stage
+cloud_init_modules:
+ - migrator
+ - seed_random
+ - bootcmd
+ - write-files
+ - set_hostname
+ - update_hostname
+ - update_etc_hosts
+ - ca-certs
+ - rsyslog
+ - users-groups
+ - ssh
+In /etc/cloud/cloud.cfg, remove the emit_upstart, ssh-import-id, +grub-dpkg, apt-pipelining, apt-config, landscape, and byobu modues +from the cloud_config section. Here is the cloud_config_modules section +after the change:
+cloud_config_modules:
+# Emit the cloud config ready event
+# this can be used by upstart jobs for ’start on cloud-config’.
+ - disk_setup
+ - mounts
+ - locale
+ - set-passwords
+ - package-update-upgrade-install
+ - timezone
+ - puppet
+ - salt-minion
+ - mcollective
+ - disable-ec2-metadata
+ - runcmd
+The default /etc/cloud/cloud.cfg file is for ubuntu, +and must be updated for RHEL and SLES. To tailor this file for RHEL and SLES:
+++
+- +
Change the disable_root: true line to: disable_root: false
- +
In the system_info section, replace distro:ubuntu with distro:rhel or distro:sles according to +the distribution you will use.
- +
Change the default user name, password, and gecos under default_user configuration section as needed for your installation.
- +
Change the groups tag to remove the user groups that are not available on this distribution. When cloud-init starts up at first time, it will create the specified users and groups. The following is a sample configuration for SLES:
++system_info: +# This will affect which distro class gets used +distro: sles + # Default user name + that default user’s groups (if added/used) +default_user: + name: sles + lock_passwd: false + plain_text_passwd: ’sles’ + gecos: sles12user + groups: users + sudo: ["ALL=(ALL) NOPASSWD:ALL"] + shell: /bin/bash +For more information on cloud-init configurations, see: http://cloudinit.readthedocs.org/en/latest/topics/examples.html
+
Enable and start the cloud-init related services by issuing the following commands:
+systemctl enable cloud-init-local.service
+systemctl start cloud-init-local.service
+systemctl enable cloud-init.service
+systemctl start cloud-init.service
+systemctl enable cloud-config.service
+systemctl start cloud-config.service
+systemctl enable cloud-final.service
+systemctl start cloud-final.service
+++If you experience problems the first time you start cloud-config.service and +cloud-final.service, try starting them again.
+
Ensure all cloud-init services are in active status by issuing the following commands:
+systemctl status cloud-init-local.service
+systemctl status cloud-init.service
+systemctl status cloud-config.service
+systemctl status cloud-final.service
+Optionally, you can start the multipath service:
+systemctl enable multipathd
+systemctl start multipathd
+systemctl status multipathd
+Remove the /var/lib/cloud directory (if it exists), so that cloud-init will +not run after a reboot:
+rm -rf /var/lib/cloud
+Enable the system repositories of the RHEL8.1 and SLES15 to ensure that they can install software via yum and zypper.
+Install cloud-init by the command:
+++
+- +
For the RHEL8.1:
+++yum install cloud-init +- +
For the SLES15:
+++zypper install cloud-init +
OpenStack on z/VM uses ConfigDrive as the data source during the +installation process. You must add the following lines to the +default configuration file, /etc/cloud/cloud.cfg. Remember to disable network +configuration because network configuration is done by zvmguestconfigure.
+# Example datasource config
+# datasource:
+# Ec2:
+#
+# metadata_urls: [ ’blah.com’ ]
+#
+# timeout: 5 # (defaults to 50 seconds)
+#
+# max_wait: 10 # (defaults to 120 seconds)
+datasource_list: [ ConfigDrive, None ]
+datasource:
+ ConfigDrive:
+ dsmode: local
+network: {config: disabled}
+NOTE: please pay attention to the indentation, otherwise, cloud-init may not +work as expected.
+Optionally, enable root login by configuring the /etc/cloud/cloud.cfg file:
+disable_root: false
+Enable and start the cloud-init related services by issuing the following commands:
+systemctl enable cloud-init-local.service
+systemctl start cloud-init-local.service
+systemctl enable cloud-init.service
+systemctl start cloud-init.service
+systemctl enable cloud-config.service
+systemctl start cloud-config.service
+systemctl enable cloud-final.service
+systemctl start cloud-final.service
+If you experience problems the first time you start cloud-config.service and +cloud-final.service, try starting them again.
+Ensure all cloud-init services are in active status by issuing the following commands:
+systemctl status cloud-init-local.service
+systemctl status cloud-init.service
+systemctl status cloud-config.service
+systemctl status cloud-final.service
+not run after a reboot:
+rm -rf /var/lib/cloud
+For Ubuntu 16.04, cloud-init0.7.8 or higher is required. The examples in this +section use cloud-init0.7.8.
+For Ubuntu 20.04, cloud-init20.1-10 is installed by default, can ignore below step1-2.
+Download cloud-init0.7.8 from https://launchpad.net/cloud-init/+download. +Untar it with this command:
+tar -zxvf cloud-init-0.7.8.tar.gz
+Issue the following commands to install cloud-init:
+cd ./cloud-init-0.7.8
+python3 setup.py build
+python3 setup.py install --init-system systemd
+NOTE: You might have to install all the dependencies that cloud-init +requires according to your source z/VM environment. For example, you might +have to install setuptools before installing cloud-init. For more information, +see https://pypi.python.org/pypi/setuptools.
+OpenStack on z/VM uses ConfigDrive as the data source during the +installation process. You must add the following lines to the +default configuration file, /etc/cloud/cloud.cfg:
+# Example datasource config
+# datasource:
+# Ec2:
+#
+# metadata_urls: [ ’blah.com’ ]
+#
+# timeout: 5 # (defaults to 50 seconds)
+#
+# max_wait: 10 # (defaults to 120 seconds)
+datasource_list: [ ConfigDrive, None ]
+datasource:
+ ConfigDrive:
+ dsmode: local
+NOTE: please pay attention to the indentation, otherwise, cloud-init may not +work as expected.
+Enable root login by configuring the /etc/cloud/cloud.cfg file:
+disable_root: false
+Optionally, you can tailor the modules that run during the cloud-config +stage or the cloud-final stage by modifying cloud_config_modules or +cloud_final_modules in /etc/cloud/cloud.cfg file. +Enable and start the cloud-init related services by issuing the following commands:
+ln -s /usr/local/bin/cloud-init /usr/bin/cloud-init
+systemctl enable cloud-init-local.service
+systemctl start cloud-init-local.service
+systemctl enable cloud-init.service
+systemctl start cloud-init.service
+systemctl enable cloud-config.service
+systemctl start cloud-config.service
+systemctl enable cloud-final.service
+systemctl start cloud-final.service
+Ensure all cloud-init services are in active status by issuing the following commands:
+systemctl status cloud-init-local.service
+systemctl status cloud-init.service
+systemctl status cloud-config.service
+systemctl status cloud-final.service
+If you intend to use persistent disks, start the multipath service:
+systemctl enable multipathd
+systemctl start multipathd
+systemctl status multipathd
+Remove the /var/lib/cloud directory (if it exists), so that cloud-init will +not run after a reboot:
+rm -rf /var/lib/cloud
+After zLinux is well configured for capture, shut down it and logoff the userid, +then perform the following steps to generate the image:
+Logon your BYOL, type the command:
+/opt/zthin/bin/creatediskimage <zLinux_userid> <vdev> <image_location>
+Where: +<zLinux_userid> is the userid of the zLinux, +<vdev> is the device number for capture, +<image_location> is the image’s store location
+If you want to import the image to Feilong, you can use REST API. +Type the following command:
+# curl http://1.2.3.4:8080/images -H "Content-Type:application/json" -H 'X-Auth-Token:<your token>' -X POST -d '{"image": {"url": "file:///var/lib/zvmsdk/images/0100", "image_meta": {"os_version": "rhel6.7"}, "image_name": "0100", "remote_host": "root@6.7.8.9"}}'
+{"rs": 0, "overallRC": 0, "modID": null, "rc": 0, "output": "", "errmsg": ""}
+Please note that if the source image is located at same server as BYOL, there is no need
+to specify the remote_host parameter in data field. And please refer to Securing Connections with Tokens to get
+your token to fill in the request area <your token>.
Verify the import result by command:
+# curl http://127.0.0.1:8080/images?imagename=0100 -X GET -H "Content-Type:application/json" -H 'X-Auth-Token:<your token>'
+{"rs": 0, "overallRC": 0, "modID": null, "rc": 0, "output": [{"image_size_in_bytes": "236435482", "disk_size_units": "1100:CYL", "md5sum": "26ddd19301d4f9c8a85e812412164bb8", "comments": null, "imagename": "0100", "imageosdistro": "rhel6.7", "type": "rootonly"}], "errmsg": ""}
+During image import you may meet following error:
+{u'rs': 10, u'overallRC': 300, u'modID': 40, u'rc': 300, u'output': u'', 'errmsg': u"Image import error:
+Copying image file from remote filesystem failed with error Warning: Permanently added '6.7.8.9' (ECDSA)
+to the list of known hosts.\r\nPermission denied, please try again.\r\nPermission denied, please try again.
+\r\nPermission denied (publickey,gssapi-keyex,gssapi-with-mic,password).\r\n"}
+If similar error happens, you need to configure the ssh authentication between +your BYOL server and the server that source image located. You need to append the +public key of the owner that running sdkserver to the .ssh/authorized_keys file of +the user where your source image located. Please refer to Configuration Sample for reference.
+This is the document that describes the installation, configuration, +and basic usages of Feilong.
+1. Feilong depends on the under-layer z/VM SMAPI support to manage +the z/VM objects. For the Feilong to work normally, the managed z/VM +system should be updated to the latest level with APARs listed in the +z/VM service Information installed.
+Note
+please make sure you applied http://www-01.ibm.com/support/docview.wss?uid=isg1VM66120 +if z/VM 6.4 is used.
+2. Feilong has to be installed inside a Linux running on z/VM. +Currently supported distros include the most current supported versions:
++++
+- +
SUSE Linux Enterprise Server 15 SP6
- +
Red Hat Enterprise Linux 9.4
- +
Ubuntu 24.04 LTS
From now on, BYOL (Bring Your Own Linux) will be used to represent +the Linux on which the Feilong will be run.
+For the Feilong to run, the BYOL must have enough free disk space (>100M). +And besides that, the following updates need to be made to the BYOL.
+
Authorize BYOL user for z/VM SMAPI call.
+VSMWORK1 AUTHLIST needs to be updated in order to make the BYOL +machine be able to issue SMAPI call. Refer to z/VM Systems Management +Application Programming for how to make it.
+Note
+It is recommend to consider increase the SMAPI long call server and DIRMAINT +DATAMOVE machine if heavy concurrent workload is going to be run through Feilong. +See z/VM Systems Management Application Programming for how to make it.
+Update BYOL definition for spawning guests.
+Assume BYOL has its definition on z/VM, it needs to have following statement in +its User Directory in order to link disk during stage of spawning guests.
+OPTION LNKNOPAS
+If under RACF, RACF command need to be executed like below while the BYOL
+is the name of the virtual machine which is going to run Feilong service.
RAC PERMIT BYOL CLASS(VMRDR) ID(VSMWORK1) ACCESS(UPDATE)
+Note
+Please note when under RACF (ESM of z/VM) is used, additional setup for SMAPI is needed +to make the BYOL able to work.
+See z/VM Systems Management Application Programming for how to make it.
+Update BYOL definition about IUCV
+Assume BYOL has its definition on z/VM, it needs to have following entry in +its User Directory in order to communicate with the managed guests by the IUCV +channel
+IUCV ANY
+See z/VM Systems Management Application Programming for how to make it.
+Enable reader device
+In order to get console output of target vm, BYOL’s reader device needs to +be enabled to receive console output spool files send from target vm
+Use the following command on BYOL itself to achieve that:
+[root@xxxx ~]# cio_ignore -r 000c
+[root@xxxx ~]# chccwdev -e 000c
+Setting device 0.0.000c online
+Done
+If something like ‘is already online’ is returned, it means reader already +online and feel free to ignore the warning.
+Enable punch device
+In order to spawn guest, BYOL needs to be able to punch files to spawned +guests’ reader, so the punch device on BYOL needs to be enabled.
+Use the following command on BYOL itself to achieve that:
+[root@xxxx ~]# cio_ignore -r 000d
+[root@xxxx ~]# chccwdev -e 000d
+Setting device 0.0.000d online
+Done
+If something like ‘is already online’ is returned, it means punch already +online and feel free to ignore the warning.
+Note
+Preparation step 2 and step 3 require to logoff then re-logon the +BYOL to make the updates become effective.
+The supported Python version includes:
+Python 2.7
Python 3+
The Open Build Service (OBS) is a generic system to build and distribute binary packages from sources in an automatic, consistent and reproducible way. +OBS builds and provides an installable version of the zthin and zvmsdk packages for each of the distributions (RHEL, SLES, Ubuntu).
+SSH onto the BYOL as root user, and then follow the following steps:
+Add the feilong AlmaLinux repository from OBS
+++++# dnf config-manager --add-repo=https://download.opensuse.org/repositories/Virtualization:/feilong/AlmaLinux_9/ +
Disable gpgkeycheck flag
+++Add the flag gpgkeycheck=0 to the +/etc/yum.repos.d/download.opensuse.org_repositories_Virtualization_feilong_AlmaLinux_9_.repo file.
+
Disable SELinux
+++Update the config file /etc/selinux/config and set SELINUX=disabled. +Make sure you reboot to ensure the changes are reflected and SELinux is disabled.
+We are considering writing SELinux policies for Feilong that would enable to not disable SELinux as a whole.
+
Install the Extra Packages for Enterprise Linux.
+++Packages in EPEL are dependencies for the feilong packages installation. +Make sure you add both the EPEL and the EPEL-Next repos.
+
Install the zthin and zvmsdk packages
+++++# dnf install zthin zvmsdk +
Skip to the SSH key authentication between consumer and BYOL section to continue.
SSH onto the BYOL as root user, and then follow the following steps:
+Register to the SUSE Package Hub using SUSEConnect and refresh the available repos list.
+++Packages in the PackageHub are dependencies for the feilong package installation
+++# SUSEConnect --product PackageHub/15.5/s390x +
Add the feilong SUSE repository from OBS
+++++# zypper ar https://download.opensuse.org/repositories/Virtualization:/feilong/SLE_15_SP5/ feilong +# zypper refresh +
Install the zthin and zvmsdk packages
+++++# zypper in zthin zvmsdk +
Skip to the SSH key authentication between consumer and BYOL section to continue.
SSH onto the BYOL as root user, and then follow the following steps:
+Add the feilong Ubuntu repository from OBS
+++++# bash -c "echo 'deb http://download.opensuse.org/repositories/home:/Aazam:/feilong/xUbuntu_24.04/ /' > /etc/apt/sources.list.d/feilong.list" +# wget http://download.opensuse.org/repositories/Virtualization:/feilong/xUbuntu_24.04/Release.key +# mv Release.key /etc/apt/trusted.gpg.d/feilong.asc +
Update the apt repository list
+++++# apt update +
Disable SELinux
+++Update the config file /etc/selinux/config and set SELINUX=disabled. +Make sure you reboot to ensure the changes are reflected and SELinux is disabled.
+We are considering writing SELinux policies for Feilong that would enable to not disable SELinux as a whole.
+
Install the zthin and zvmsdk packages
+++++# apt-get install zthin zvmsdk +
Skip to the SSH key authentication between consumer and BYOL section to continue.
zthin is a library written in C that works as part of the Feilong. +It mainly focuses on socket connection from BYOL to z/VM SMAPI(System Management API). +Feilong requires zthin as the backend to communicate with z/VM SMAPI, +thus it needs to be installed before installing Feilong.
+SSH onto the BYOL as root user, and then follow the following steps:
+Clone build project from github
+# git clone https://github.com/mfcloud/build-zvmsdk.git
+# cd build-zvmsdk
+Trigger the build tool
+The build tool depends on the following commands: rpmbuild, gcc, so you should make +sure these commands are usable on BYOL before running the following build.
+For building on RHEL
+# /usr/bin/bash buildzthinrpm_rhel master
+For building on SLES
+# /usr/bin/bash buildzthinrpm_sles master
+If this build finishes successfully, the resulting rpm package will be generated +in the /root/zthin-build/RPMS/s390x/ directory named in the format +zthin-version-snapdate.s390x.rpm where version is the zthin version +number and date is the build date.
+For building on Debian, make sure you have dpkg-dev available.
+ # /usr/bin/bash buildzthindeb master
+
+If the build finishes successfully, the resulting deb package will be generated
+in the /root/build-zvmsdk/feilong directory named in the format
+*zthin-version.s390x.deb* where *version* is the zthin version
+number and *date* is the build date.
+Install the rpm or deb generated in last step
+# rpm -ivh /root/zthin-build/RPMS/s390x/zthin-3.1.0-snap201710300123.s390x.rpm
+Be sure to replace the zthin-3.1.0-snap201710300123.s390x.rpm with the correct version name.
+# dpkg -i /root/build-zvmsdk/feilong/zthin-3.1.2.s390x.deb
+Be sure to replace the zthin-3.1.2.s390x.deb with the correct version name.
+Verify zthin can work
+# /opt/zthin/bin/smcli Image_Query_DM -T opncloud
+If all things went well, this smcli command should be +able to return the directory entry of user OPNCLOUD.
+If this command failed, you need to check the following items:
+The BYOL user is successfully authorized to issue SMAPI call.
The SMAPI server on this z/VM host is working normally.
The zthin rpm is installed without any error.
Optionally, Consider to add /opt/zthin/bin/ into $PATH so you can use smcli command directly.
z/VM SDK is the upper transition layer of Feilong. It implements the +supported SDK APIs by communicating with the zthin backend.
+Install z/VM sdk
+++Please ensure to update your setuptools to the latest version before doing this step, +the following installation step would rely on it to automatically install the depended +python packages.
+++# git clone https://github.com/mfcloud/build-zvmsdk.git +# cd build-zvmsdk +
Trigger the build tool
+The build tool depends on the following commands: rpmbuild, gcc, so you should make +sure these commands are usable on BYOL before running the following build.
+For building on RHEL
+# /usr/bin/bash buildzvmdsdkrpm_rhel master
+For building on SLES
+# /usr/bin/bash buildzvmsdkrpm_sles master
+If this build finishes successfully, the resulting rpm package will be generated +in the /root/zvmsdk-build/RPMS/s390x/ directory named in the format +zvmsdk-version-snapdate.s390x.rpm where version is the zvmsdk version +number and date is the build date.
+For building on Debian, make sure you have dpkg-dev available.
+# /usr/bin/bash buildzvmsdkdeb master
+If the build finishes successfully, the resulting deb package will be generated +in the /root/build-zvmsdk/ directory named in the format +zvmsdk-version.s390x.deb where version is the zthin version +number and date is the build date.
+Install the rpm or deb generated in last step
+# rpm -ivh /root/zvmsdk/RPMS/s390x/zvmsdk-1.4.0-snap201710300123.s390x.rpm
+Be sure to replace the zvmsdk-1.4.0-snap201710300123.s390x.rpm with the correct version name.
+# dpkg -i /root/build-zvmsdk/feilong/zvmsdk-1.4.0.s390x.deb
+Be sure to replace the zvmsdk-1.4.0.s390x.deb with the correct version name.
+If the z/VM SDK was installed via python setup.py install, you can fetch and
+checkout to new version, then upgrade it by issue python setup.py install again.
Note
+If you upgrade from a version equal or lower than 1.6.2 to 1.6.3 or newer version,
+you have to add two new columns - wwpn_npiv and wwpn_phy into fcp table in
+sdk_fcp database with type `varchar(16)`, which is located at
+/var/lib/zvmsdk/databases/sdk_fcp.sqlite, for example, by sqlite3 command:
+ALTER TABLE fcp ADD COLUMN wwpn_npiv varchar(16) and
+ALTER TABLE fcp ADD COLUMN wwpn_phy varchar(16)
After z/VM SDK is installed, a file named ‘zvmsdk.conf.sample’ is generated +under the /etc/zvmsdk/ folder. It contains all the supported configurations +for z/VM SDK. You can refer to it to create your own configuration file which +should be named as zvmsdk.conf.
+Here’s a sample configuration in which several options marked as ‘required’ +should be customized according to your environment.
+[database]
+dir=/var/lib/zvmsdk/databases/
+
+[image]
+sdk_image_repository=/var/lib/zvmsdk/images
+
+[logging]
+log_level=INFO
+log_dir=/var/log/zvmsdk/
+
+[network]
+# IP address of the Linux machine which is running SDK on.
+# This config option is required
+my_ip=127.0.0.1
+
+[sdkserver]
+bind_addr=127.0.0.1
+bind_port=2000
+max_worker_count=64
+
+[wsgi]
+auth=none
+
+[zvm]
+# zVM disk pool and type for root/ephemeral disks.
+# This config option is required
+disk_pool=ECKD:eckdpool
+
+# PROFILE name to use when creating a z/VM guest.
+# This config option is required
+user_profile=osdflt
+
+# The default maximum number of virtual processers the user can define.
+user_default_max_cpu=32
+
+# The default maximum size of memory the user can define.
+user_default_max_memory=64G
+For the details of all configuration options, please refer to +Configuration Options.
+The Feilong is designed to be run inside a daemon. The daemon server is bond to +the configured socket for receiving requests and then call the requested SDK API.
+The daemon server would be run with user ‘zvmsdk’ and group ‘zvmsdk’, the following user and folder +setup should be made on BYOL for the z/VM SDK daemon to run.
+Create ‘zvmsdk’ user and group
+# useradd -d /var/lib/zvmsdk/ -m -U -p PASSWORD zvmsdk
+Replace the PASSWORD with your own password for the new created user.
+Configure sudo access for ‘zvmsdk’ user (optional)
+If Feilong is installed from source code python setup.py install or from package install
+such as deb or rpm, then you can skip this step as it’s already done during install stage.
The z/VM SDK Daemon relies on some privileged commands for the management of the z/VM host, so you +need to grant the ‘zvmsdk’ user to run following commands with sudo without password:
+/usr/sbin/vmcp
/opt/zthin/bin/smcli
/usr/sbin/chccwdev
/usr/sbin/cio_ignore
/usr/sbin/fdasd
/usr/sbin/fdisk
/usr/sbin/vmur
/usr/bin/mount
/usr/bin/umount
/usr/sbin/mkfs
/usr/sbin/mkfs.xfs
/usr/sbin/dasdfmt
/opt/zthin/bin/unpackdiskimage
/opt/zthin/bin/creatediskimage
/opt/zthin/bin/linkdiskandbringonline
/opt/zthin/bin/offlinediskanddetach
A sample is given in the following block, copy the content to /etc/sudoers.d/zvmsdk:
+# cat /etc/sudoers.d/zvmsdk
+zvmsdk ALL = (ALL) NOPASSWD:/usr/sbin/vmcp, /opt/zthin/bin/smcli, /usr/sbin/chccwdev, /usr/sbin/cio_ignore, /usr/sbin/fdasd, /usr/sbin/fdisk, /usr/sbin/vmur, /usr/bin/mount, /usr/bin/umount, /usr/sbin/mkfs, /usr/sbin/mkfs.xfs, /usr/sbin/dasdfmt, /opt/zthin/bin/unpackdiskimage, /opt/zthin/bin/creatediskimage, /opt/zthin/bin/linkdiskandbringonline, /opt/zthin/bin/offlinediskanddetach
+Setup home directory
+# mkdir -p /var/lib/zvmsdk
+# chown -R zvmsdk:zvmsdk /var/lib/zvmsdk
+# chmod -R 755 /var/lib/zvmsdk
+Setup log directory
+The folder to which the z/VM SDK log would be written to can be configured with the ‘log_dir’ +option in ‘default’ section. By default, the log folder is ‘/var/log/zvmsdk’. If you have customized +the ‘log_dir’ value, you need to change the folder in following commands accordingly.
+# mkdir -p /var/log/zvmsdk
+# chown -R zvmsdk:zvmsdk /var/log/zvmsdk
+# chmod -R 755 /var/log/zvmsdk
+Setup configuration directory
+# mkdir -p /etc/zvmsdk
+# chown -R zvmsdk:zvmsdk /etc/zvmsdk
+# chmod -R 755 /etc/zvmsdk
+# ls -l /etc/zvmsdk
+A file named zvmsdk.conf should be found under /etc/zvmsdk folder and contains at least all the required +options before the z/VM SDK daemon can be started.
+For image import/export function, BYOL’s running user(eg zvmsdk) needs to be +authorized by the user of the consumer (eg nova-compute) if they are not in +same host. For example, if you want to import/export image from/to nova +compute server，please make ensure you can ssh nova@nova-compute-ip without +password from zvmsdk user on BYOL server. Refer to the following steps to +configure it:
+Logon to the nova-compute server and change the nova user’s right to be +able to log in, and make sure port 22 is open.
+ssh root@nova-compute-ip
+usermod -s /bin/bash nova
+where: +nova-compute-ip: is the IP address of the nova compute node.
+Change to nova user and inject the zvmsdk server’s public key into it.
+su - nova
+scp zvmsdk@zvmsdk-ip:/var/lib/zvmsdk/.ssh/id_rsa.pub $HOME mkdir -p $HOME/.ssh
+mv $HOME/id_rsa.pub $HOME/.ssh/authorized_keys
+where: +zvmsdk: is the user on the BYOL server that runs the z/VM SDK. +zvmsdk-ip: is the IP address of the BYOL server +Note: If the $HOME/.ssh/authorized_keys file already exists, +you just need to append the BYOL’s public key to it.
+Ensure that the file mode under the $HOME/.ssh folder is 644.
+chmod -R 644 $HOME/.ssh/*
+Issue the following command to determine if SELinux is enabled on the system.
+getenforce
+If SELinux is enabled then set SELinux contexts on the nova home directory.
+su -
+chcon -R -t ssh_home_t nova_home
+where: +nova_home：is the home directory for the nova user on the nova compute server. +You can obtain nova_home by issuing: echo ~nova
+NOTE: If the host key of nova-compute server changed, please run +the following command on zvmsdk server to clean the cached host key of +nova-compute server from zvmsdk server’s known_hosts file
+ssh-keygen -R nova-compute-ip
+Configure the sdkserver service to start automatically at boot by command: +.. code-block:: text
+++# systemctl enable sdkserver
+
The z/VM SDK Daemon can be started via the following command:
+# systemctl start sdkserver
+And make sure the sdkserver service status is ‘active (running)’ as following:
+# systemctl status sdkserver
+● sdkserver.service - zVM SDK API server
+ Loaded: loaded (/usr/lib/systemd/system/sdkserver.service; disabled; vendor preset: disabled)
+ Active: active (running) since Mon 2017-11-20 00:47:18 EST; 3s ago
+ Main PID: 5779 (sdkserver)
+ CGroup: /system.slice/sdkserver.service
+ └─5779 /usr/bin/python /usr/bin/sdkserver
+
+Nov 20 00:47:18 0822rhel7 systemd[1]: Started zVM SDK API server.
+Nov 20 00:47:18 0822rhel7 systemd[1]: Starting zVM SDK API server...
+Nov 20 00:47:18 0822rhel7 sdkserver[5779]: INFO: [MainThread] SDK server now listening
+You can verify that the process is listenning on the configured port. +For example:
+# netstat -anp | grep 2000
+tcp 0 0 127.0.0.1:2000 0.0.0.0:* LISTEN 56434/python
+This section provides info on how resize an image to a bigger size disk +during deploy process was performed.
+The following sample describes:
+Create a 3390 disk with 2300 cylinders.
Capture the disk and make it a deployable image.
Deploy the image (this sample use openstack) to larger number cylinders, this sample using 10G disk size, which is 14564 cylinders.
After deploy, the new spawned guest has 10G disk size.
Note only the size of last partition has been enlarged.
Note
+Following test result only tested on SLES12SP4 for now.
+Create a 3390 disk with 2300 cylinders has 2 partitions.
+++++q v dasd +00: DASD 0100 3390 JM6013 R/W 2300 CYL ON DASD 6013 SUBCHANNEL = 0001 + +# lsdasd +Bus-ID Status Name Device Type BlkSz Size Blocks +============================================================================== +0.0.0100 active dasda 94:0 ECKD 4096 1617MB 414000 + +# fdasd --table /dev/dasda +WARNING: Your DASD '/dev/dasda' is in use. +If you proceed, you can heavily damage your system. +If possible exit all applications using this disk +and/or unmount it. + +reading volume label ..: VOL1 +reading vtoc ..........: ok + +Disk /dev/dasda: + cylinders ............: 2300 + tracks per cylinder ..: 15 + blocks per track .....: 12 + bytes per block ......: 4096 + volume label .........: VOL1 + volume serial ........: 0X0100 + max partitions .......: 3 + +------------------------------- tracks ------------------------------- + Device start end length Id System + /dev/dasda1 2 4267 4266 1 Linux native + /dev/dasda2 4268 34499 30232 2 Linux native +exiting... + +# parted /dev/dasda print +Model: IBM S390 DASD drive (dasd) +Disk /dev/dasda: 1696MB +Sector size (logical/physical): 512B/4096B +Partition Table: dasd +Disk Flags: + +Number Start End Size File system Flags + 1 98.3kB 210MB 210MB ext2 + 2 210MB 1696MB 1486MB ext4 +
The disk size of the guest where the sles12 sp4 image was deployed using openstack.:
+++++# openstack flavor list +| ID | Name | RAM | Disk | Ephemeral | VCPUs | Is Public | +| d80df349-e277-4c08-a578-10dd8ff5ba02 | zvm-small | 2048 | 10 | 0 | 2 | True | + +# openstack server show s124-2part-ext4 +| flavor | zvm-small (d80df349-e277-4c08-a578-10dd8ff5ba02) | + +s124-2part-ext4:~ # vmcp q v dasd +DASD 0100 3390 JM601B R/W 14564 CYL ON DASD 601B SUBCHANNEL = 0003 + +s124-2part-ext4:~ # lsdasd +Bus-ID Status Name Device Type BlkSz Size Blocks +============================================================================== +0.0.0100 active dasda 94:0 ECKD 4096 10240MB 2621520 + +s124-2part-ext4:~ # fdasd --table /dev/dasda + +WARNING: Your DASD '/dev/dasda' is in use. + If you proceed, you can heavily damage your system. + If possible exit all applications using this disk + and/or unmount it. + +reading volume label ..: VOL1 +reading vtoc ..........: ok + +Disk /dev/dasda: + cylinders ............: 14564 + tracks per cylinder ..: 15 + blocks per track .....: 12 + bytes per block ......: 4096 + volume label .........: VOL1 + volume serial ........: 0X0100 + max partitions .......: 3 + +------------------------------- tracks ------------------------------- + Device start end length Id System + /dev/dasda1 2 4267 4266 1 Linux native + /dev/dasda2 4268 218459 214192 2 Linux native + exiting... + +s124-2part-ext4:~ # parted /dev/dasda print +Model: IBM S390 DASD drive (dasd) +Disk /dev/dasda: 10.7GB +Sector size (logical/physical): 512B/4096B +Partition Table: dasd +Disk Flags: + +Number Start End Size File system Flags + 1 98.3kB 210MB 210MB ext2 + 2 210MB 10.7GB 10.5GB ext4 +
The last partition on dasda was the partition that was expanded to fill the remainder of the ECKD disk .
+This is a reference for the Feilong RESTful API.
+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)
Lists version of this API.
+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"
+ }
+}
+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 Securing Connections with Tokens to get more details.
+GET /smapi_health
+Get health status of the 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 fail. |
+
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.
+Lists, creates, shows details for, updates, and deletes 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"]
+}
+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, |
+
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 |
+
format (Optional) |
+body |
+string |
+Format of disk, can be |
+
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
+ |
+
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 digits 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 |
+
format (Optional) |
+body |
+string |
+Format of disk, can be |
+
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 |
+
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"}]
+}
+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 info 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 |
+
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 |
+
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'}]
+
+ }
+}
+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 |
+
format (Optional) |
+body |
+string |
+Format of disk, can be |
+
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
+ |
+
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 |
+
format (Optional) |
+body |
+string |
+Format of disk, can be |
+
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 |
+
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"}]
+}
+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 |
+
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
+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, |
+
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
+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 start with |
+
target_lun |
+body |
+string |
+Logical Unit Number, must start with |
+
os_version |
+body |
+string |
+Operating system version, the valid alues are: rhel6.x, rhel7.x, rhel8.x, +rhel9.x, sles11.x, sles12.x, sles15.x, ubuntu16.x, ubuntu20.x, ubuntu22.x, rhcos4.x, +all case insensitive. Please contact 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
+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 start with |
+
target_lun |
+body |
+string |
+Logical Unit Number, must start with |
+
os_version |
+body |
+string |
+Operating system version, the valid alues are: rhel6.x, rhel7.x, rhel8.x, +rhel9.x, sles11.x, sles12.x, sles15.x, ubuntu16.x, ubuntu20.x, ubuntu22.x, rhcos4.x, +all case insensitive. Please contact 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
+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 |
+
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 KBytes. |
+
max_mem_kb |
+body |
+integer |
+The maximum memory in KBytes that can be allocated for this guest. |
+
min_mem_kb |
+body |
+integer |
+The maximum memory in KBytes that can be allocated for this guest. |
+
shared_mem_kb |
+body |
+integer |
+Shared memory in KBytes. |
+
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
+ }
+ }
+}
+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 |
+
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
+ }
+ ]
+ }
+}
+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": ""
+}
+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 with only one entry describing user directory. |
+
Response sample:
{
+ "rs": 0,
+ "overallRC": 0,
+ "modID": null,
+ "rc": 0,
+ "errmsg": "",
+ "output": {"user_direct": ["USER1", "INCLUDE PROFILE"]}
+}
+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
+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 |
+
Response sample:
{
+ "rs": 0,
+ "overllRC": 0,
+ "modID": null,
+ "rc": 0,
+ "errmsg": "",
+ "output": "off"
+}
+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 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 |
+
mem_kb |
+body |
+integer |
+Memory 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
+ }
+}
+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"]}
+}
+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. |
+
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, |
+
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'}]
+ }
+}
+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. |
+
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:
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 alues are: rhel6.x, rhel7.x, rhel8.x, +rhel9.x, sles11.x, sles12.x, sles15.x, ubuntu16.x, ubuntu20.x, ubuntu22.x, 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 info list of guest. It has one dictionary that contain some of the below +keys for each interface. All the keys are optional : +
|
+
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:
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 alues are: rhel6.x, rhel7.x, rhel8.x, +rhel9.x, sles11.x, sles12.x, sles15.x, ubuntu16.x, ubuntu20.x, ubuntu22.x, 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 |
+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:
Start a guest.
+POST /guests/{userid}/action
+Request:
Name |
+In |
+Type |
+Description |
+
|---|---|---|---|
userid |
+path |
+string |
+Guest userid |
+
action |
+body |
+string |
+Take |
+
Request sample:
{
+ "action": "start"
+}
+Response code:
+HTTP status code 200 on success.
+Response contents:
Stop a guest.
+POST /guests/{userid}/action
+Request:
Name |
+In |
+Type |
+Description |
+
|---|---|---|---|
userid |
+path |
+string |
+Guest userid |
+
action |
+body |
+string |
+Take |
+
Request sample:
{
+ "action": "stop"
+}
+Response code:
+HTTP status code 200 on success.
+Response contents:
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 |
+
Request sample:
{
+ "action": "softstop"
+}
+Response code:
+HTTP status code 200 on success.
+Response contents:
Pause a guest.
+POST /guests/{userid}/action
+Request:
Name |
+In |
+Type |
+Description |
+
|---|---|---|---|
userid |
+path |
+string |
+Guest userid |
+
action |
+body |
+string |
+Take |
+
Request sample:
{
+ "action": "pause"
+}
+Response code:
+HTTP status code 200 on success.
+Response contents:
Unpause a guest.
+POST /guests/{userid}/action
+Request:
Name |
+In |
+Type |
+Description |
+
|---|---|---|---|
userid |
+path |
+string |
+Guest userid |
+
action |
+body |
+string |
+Take |
+
Request sample:
{
+ "action": "unpause"
+}
+Response code:
+HTTP status code 200 on success.
+Response contents:
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 |
+
Request sample:
{
+ "action": "reboot"
+}
+Response code:
+HTTP status code 200 on success.
+Response contents:
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 |
+
Request sample:
{
+ "action": "reset"
+}
+Response code:
+HTTP status code 200 on success.
+Response contents:
POST /guests/{userid}/action
+Get console output of guest.
+Request:
Name |
+In |
+Type |
+Description |
+
|---|---|---|---|
userid |
+path |
+string |
+Guest userid |
+
action |
+body |
+string |
+Take |
+
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.
+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 |
+
dest_zcc_userid (Optional) |
+body |
+string |
+The userid of zcc on destination node.
+Required if |
+
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 |
+
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:
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 |
+
meta |
+body |
+string |
+The metadata of the vm to be registered. |
+
net_set |
+body |
+string |
+Guest network configured or not.
+ |
+
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:
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 |
+
Request sample:
{
+ "action": "deregister_vm",
+}
+Response code:
+HTTP status code 200 on success.
+Response contents:
POST /guests/{userid}/action
+Live resize CPUs of guest.
+Request:
Name |
+In |
+Type |
+Description |
+
|---|---|---|---|
userid |
+path |
+string |
+Guest userid |
+
action |
+body |
+string |
+Take |
+
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
+POST /guests/{userid}/action
+Resize CPUs of guest.
+Request:
Name |
+In |
+Type |
+Description |
+
|---|---|---|---|
userid |
+path |
+string |
+Guest userid |
+
action |
+body |
+string |
+Take |
+
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).
POST /guests/{userid}/action
+Live resize memory of guest.
+Request:
Name |
+In |
+Type |
+Description |
+
|---|---|---|---|
userid |
+path |
+string |
+Guest userid |
+
action |
+body |
+string |
+Take |
+
size |
+body |
+string |
+The size of memory that the guest should have after resize. +The value should be specified by 1-4 digits 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
+POST /guests/{userid}/action
+Resize memory of guest.
+Request:
Name |
+In |
+Type |
+Description |
+
|---|---|---|---|
userid |
+path |
+string |
+Guest userid |
+
action |
+body |
+string |
+Take |
+
size |
+body |
+string |
+The size of memory that the guest should have after resize. +The value should be specified by 1-4 digits 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).
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 |
+
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, |
+
vdev (Optional) |
+body |
+string |
+Device number to which the image will be deployed, 1- to 4- hexadecimal
+digits. |
+
hostname (Optional) |
+body |
+string |
+hostname of the guest. Will be ignored if |
+
skipdiskcopy (Optional) |
+body |
+boolean |
+whether to skip the copy of image to disk. Default value if False.
+If the value is True, the |
+
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:
POST /guests/{userid}/action
+Request:
Name |
+In |
+Type |
+Description |
+
|---|---|---|---|
userid |
+path |
+string |
+Guest userid |
+
action |
+body |
+string |
+Take |
+
image |
+body |
+string |
+Image name that can be uniquely identify an image. |
+
capture_type (Optional) |
+body |
+string |
+The type of capture: +
|
+
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:
POST /guests/{userid}/action
+Request:
Name |
+In |
+Type |
+Description |
+
|---|---|---|---|
userid |
+path |
+string |
+Guest userid |
+
action |
+body |
+string |
+Take |
+
os_version |
+body |
+string |
+Operating system version, the valid alues are: rhel6.x, rhel7.x, rhel8.x, +rhel9.x, sles11.x, sles12.x, sles15.x, ubuntu16.x, ubuntu20.x, ubuntu22.x, 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:
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 |
+
Response sample:
{
+ "rs": 0,
+ "overallRC": 0,
+ "modID": null,
+ "rc": 0,
+ "errmsg": "",
+ "output": "off"
+}
+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.
+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.
+Get guests list, info from host (hypervisor) running on.
+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.
+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
+ }
+}
+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": ""
+}
+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": ""
+}
+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": ""
+}
+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",
+ ""
+ ]
+}
+Lists, creates, shows details for, updates, and deletes 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 alues are: rhel6.x, rhel7.x, rhel8.x, +rhel9.x, sles11.x, sles12.x, sles15.x, ubuntu16.x, ubuntu20.x, ubuntu22.x, 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, 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 |
+
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": ""
+}
+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. |
+
image_meta |
+body |
+dict |
+The metadata which 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, 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 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, |
+
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.
+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. |
+
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, |
+
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"}
+}
+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": ""
+}
+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.
+Lists, creates, updates, and deletes 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. |
+
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 : +
|
+
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 : +
|
+
vid (Optional) |
+body |
+string, integer |
+The VLAN ID. This can be any of the following values:
+ |
+
port_type (Optional) |
+body |
+string |
+Port type : +
|
+
gvrp (Optional) |
+body |
+string |
+gvrp : +
|
+
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 |
+
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.
+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"]
+}
+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": ""
+}
+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.
+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.
+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 |
+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.
+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.
+Handling of volumes and FCP devices.
+PUT /volumes/volume_refresh_bootmap
+Refresh a volume’s bootmap info.
+Request:
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 : +
|
+
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
+}
+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": ''
+ }
+}
+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].
+ |
+
Response sample:
{
+ "rs": 0,
+ "overallRC": 0,
+ "modID": null,
+ "rc": 0,
+ "errmsg": "",
+ "output": ['testid', 1, 3]
+}
+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 |
+body |
+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.
+Imports and exports raw file data.
+These operations may be restricted to Feilong administrators.
+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:
+“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"}
+}
+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.
+GET /switch
+Get Switch information based on port id.
+Request:
Name |
+In |
+Type |
+Description |
+
|---|---|---|---|
portid |
+body |
+string |
+The ID of the port. |
+
Response code:
+HTTP status code 200 on success.
+Response sample:
{
+ "rs": 0,
+ "overallRC": 0,
+ "modID": null,
+ "rc": 0,
+ "errmsg": "",
+ "output": {['TEST0045', '4000', 'VSTEST', 'da19c4b3-905b-4844-898e-e36813be796e', None]}
+}
+This section introduces the basics of using Feilong to manage z/VM host, and gives some usage examples.
+
+Image import from external image repository into Feilong; for one image, this only needs to be done once
Store the information into DB record
Call from upper layer to create a guest
SMAPI calls DIRMAINT to define a user direct
Call from upper layer to deploy a guest
Feilong then starts to copy disk contents from image to the disks allocated in step 3
Post deploy actions such as network setup, and send customized files from Feilong to the newly deployed VM
Start the VM
During first power on of the VM, set up the network and utilize the customized files to update network, hostname etc (by default, using cloud-init)
+Call from upper layer to trigger the Vswitch create call
HTTP service (Feilong REST API) gets the request and handles it to Feilong server
SMAPI is then called and handles the VSWITCH create command, this will include persistent definition of Vswitch and define it in z/VM CP
CP is called to create vswitch on the fly
The following examples show how to spawn a new VM, both in bash and in python.
+Note: other language bindings exist, for example for golang.
+In these examples, the Feilong connector runs at the IP address 1.2.3.4.
+Create a parameters file named “create-guest-id001.json”:
+{
+ "guest":
+ {
+ "userid": "myguest",
+ "vcpus": 2,
+ "memory": 2048,
+ "user_profile": "osdflt",
+ "disk_list": [
+ {
+ "size": "5g",
+ "is_boot_disk": true,
+ "disk_pool": "ECKD:vmpool"
+ } ],
+ "max_cpu": 4,
+ "max_mem": "4G"
+ }
+}
+Call “curl” command, referring to this parameters file:
+$ curl -s -X POST \
+ -H "Content-Type: application/json" \
+ -d @create-guest-id001.json \
+ http://1.2.3.4/guests | jq
+++++from zvmconnector import connector + +userid = 'myguest' +vcpus = 2 +memory = 2048 +user_profile = 'osdflt' +disk_list = [ + { + 'size': "5g", + 'is_boot_disk': True, + 'disk_pool': 'ECKD:vmpool' + } ] +max_cpu = 4 +max_mem = '4G' + +client = connector.ZVMConnector( + connection_type = 'rest', ip_addr = '1.2.3.4', port = '80') + +guest_create_info = client.send_request( + 'guest_create', userid, vcpus, memory, + disk_list = disk_list, user_profile = user_profile, max_cpu = max_cpu, max_mem = max_mem) + +if guest_create_info['overallRC']: + raise RuntimeError('Failed to create guest: ' + guest_create_info['errmsg']) + +print('Guest created') +
+ Searching for multiple words only shows matches that contain + all words. +
+ + + + + + + + + +Each Feilong API is exposed through a RESTful interface, higher level +systems can manage z/VM by consuming these RESTful APIs directly.
+This chapter describes how to setup a web server for hosting the Feilong RESTful APIs.
+The recommended deployment for Feilong is to have a web server such as +Apache httpd or nginx handle the HTTP connections and proxy requests to the independent +z/VM SDK server running under a wsgi container such as uwsgi +or directly connected via Apache’s wsgi module.
+The detailed setup steps for each type of web server is out of this document’s range, +you can refer to the specific guide of your chosen web server. This guide walks you through +the deployment process, either:
++++
+- +
with premade packages (which use the mod_wsgi method);
- +
manually, with uwsgi;
- +
or manually, with Apache’s mod_wsgi.
This matrix represents the successful setup of different web servers across three Linux distributions. +The last section of this chapter details about using tokens to enhance security.
+Tested |
+RHEL 9.4 |
+SLES 15 SP6 |
+Ubuntu 24.04 |
+
|---|---|---|---|
Apache2 + uwsgi |
+✓ |
++ | ✓ |
+
Apache2 + mod_wsgi |
+✓ |
+✓ |
+✓ |
+
nginx + uwsgi |
++ | + | ✓ |
+
The following instructions are for RHEL 9.4. +The RPM packages can be downloaded from https://download.opensuse.org/repositories/Virtualization:/feilong/AlmaLinux_9/ .
+Install the downloaded packages zthin and zvmsdk using the yum or dnf command +If not already done, enable the automatic startup of the Apache server, and then start it:
+..code-block:: text
+++# systemctl enable httpd +# systemctl start httpd
+
Finally, you can verify if the installation works as intended by making a curl request from your workstation
+..code-block:: text
+++$ curl http://<your server ip address>:8080/
+
By default, Feilong will listen on port 8080. +To change that, you need to modify both Apache configuration and firewall rules.
+The following instructions are for SLES15 SP6. +The RPM packages can be downloaded from https://download.opensuse.org/repositories/Virtualization:/feilong/SLE_15_SP5/
+Install the downloaded packages using the zypper command +If not already done, enable the automatic startup of the Apache server, and then start it:
+..code-block:: text
+++# systemctl enable apache2 +# systemctl start apache2
+
Finally, you can verify if the installation works as intended by making a curl request from your workstation
+..code-block:: text
+++$ curl http://<your server ip address>:8080/
+
By default, Feilong will listen on port 8080. +To change that, you need to modify both Apache configuration and firewall rules.
+The following instructions are for Ubuntu 24.04. +The RPM packages can be downloaded from https://download.opensuse.org/repositories/Virtualization:/feilong/xUbuntu_24.04/
+Install the downloaded packages using the apt command +If not already done, enable the automatic startup of the Apache server, and then start it:
+..code-block:: text
+++# systemctl enable apache2 +# systemctl start apache2
+
Finally, you can verify if the installation works as intended by making a curl request from your workstation
+..code-block:: text
+++$ curl http://<your server ip address>:8080/
+
By default, Feilong will listen on port 8080. +To change that, you need to modify both Apache configuration and firewall rules.
+The following packages need to be installed:
+Apache httpd server
Apache modules: mod_proxy_uwsgi
uwsgi
uwsgi plugin for python: uwsgi-plugin-python
Usually the configuration can be placed at /etc/uwsgi.d/ folder, for example, named as +/etc/uwsgi.d/your_config.ini. Update the file to match your system configuration.
+The sample below indicated the uwsgi service will be running at port 35000 +so apache server can connect port 35000 and communicate with it
+[uwsgi]
+chmod-socket = 666
+uwsgi-socket = 127.0.0.1:35000
+lazy-apps = true
+add-header = Connection: close
+buffer-size = 65535
+thunder-lock = true
+plugins = python
+enable-threads = true
+exit-on-reload = true
+die-on-term = true
+master = true
+processes = 2
+threads = 32
+wsgi-file = /usr/bin/zvmsdk-wsgi
+pidfile = /tmp/zvmsdk-wsgi.pid
+socket = /tmp/zvmsdk-wsgi.socket
+uid = zvmsdk
+gid = zvmsdk
+logto = /var/log/zvmsdk/uwsgi.log
+Create a uwsgi service
+Use following sample to create a uwsgi service for running the Feilong. +For RHEL7.2, put this file as /usr/lib/systemd/system/zvmsdk-wsgi.service.
+[Unit]
+Description=Feilong uwsgi
+After=syslog.target network.target httpd.service
+
+[Service]
+Type=simple
+ExecStart=/usr/sbin/uwsgi --ini /etc/uwsgi.d/your_config.ini
+ExecReload=/usr/sbin/uwsgi --reload /etc/uwsgi.d/your_config.ini
+ExecStop=/usr/sbin/uwsgi --stop /etc/uwsgi.d/your_config.ini
+
+[Install]
+WantedBy=multi-user.target
+Enable zvmsdk uwsgi service
+#systemctl enable zvmsdk-wsgi.service
+Start zvmsdk uwsgi service
+#systemctl start zvmsdk-wsgi.service
+Verify zvmsdk uwsgi service status
+Verify the zvmsdk uwsgi service is started normally and the status is active (running) +in the following command output.
+[root@0822rhel7 ~]# systemctl status zvmsdk-wsgi.service
+● zvmsdk-wsgi.service - Feilong uwsgi
+ Loaded: loaded (/usr/lib/systemd/system/zvmsdk-wsgi.service; disabled; vendor preset: disabled)
+ Active: active (running) since Tue 2017-11-21 21:58:06 EST; 13min ago
+ Main PID: 7227 (uwsgi)
+ CGroup: /system.slice/zvmsdk-wsgi.service
+ ├─7227 /usr/sbin/uwsgi --ini /etc/uwsgi.d/zvmsdk-wsgi.ini
+ ├─7229 /usr/sbin/uwsgi --ini /etc/uwsgi.d/zvmsdk-wsgi.ini
+ └─7230 /usr/sbin/uwsgi --ini /etc/uwsgi.d/zvmsdk-wsgi.ini
+
+Nov 21 21:58:06 0822rhel7 uwsgi[7227]: your server socket listen backlog is limited to 100 connections
+Nov 21 21:58:06 0822rhel7 uwsgi[7227]: your mercy for graceful operations on workers is 60 seconds
+Nov 21 21:58:06 0822rhel7 uwsgi[7227]: mapped 402621 bytes (393 KB) for 2 cores
+Nov 21 21:58:06 0822rhel7 uwsgi[7227]: *** Operational MODE: preforking ***
+Nov 21 21:58:06 0822rhel7 uwsgi[7227]: *** uWSGI is running in multiple interpreter mode ***
+Nov 21 21:58:06 0822rhel7 uwsgi[7227]: spawned uWSGI master process (pid: 7227)
+Nov 21 21:58:06 0822rhel7 uwsgi[7227]: spawned uWSGI worker 1 (pid: 7229, cores: 1)
+Nov 21 21:58:06 0822rhel7 uwsgi[7227]: spawned uWSGI worker 2 (pid: 7230, cores: 1)
+Nov 21 21:58:06 0822rhel7 uwsgi[7227]: *** no app loaded. going in full dynamic mode ***
+Nov 21 21:58:06 0822rhel7 uwsgi[7227]: *** no app loaded. going in full dynamic mode ***
+And the uwsgi process is listenning on port 35000:
+# netstat -anp | grep 35000
+tcp 0 0 127.0.0.1:35000 0.0.0.0:* LISTEN 7227/uwsgi
+
+# curl -v http://127.0.0.1:35000/
+* About to connect() to 127.0.0.1 port 35000 (#0)
+* Trying 127.0.0.1...
+* Connected to 127.0.0.1 (127.0.0.1) port 35000 (#0)
+> GET / HTTP/1.1
+> User-Agent: curl/7.29.0
+> Host: 127.0.0.1:35000
+> Accept: */*
+>
+* Empty reply from server
+* Connection #0 to host 127.0.0.1 left intact
+curl: (52) Empty reply from server
+Use the following sample as a start for apache to proxy requests to Feilong +wsgi service, copy the content to /etc/httpd/conf.d/zvmsdk.conf and update the file to match +your system and requirements.
+Note
+Sometimes the REST API call will takes some time to complete while the default timeout +is not enough to complete the handle of the request, for example, Apache Timeout +shows the default timeout value of Apache httpd server is 60, administrator need to +set a bigger value (for example 3600) to avoid time out error.
+Under this sample’s configuration settings, the httpd server will listen on port 8080 +and any incoming request on it will be redirected to zvmsdk wsgi which is listening +at port 35000
+LoadModule proxy_uwsgi_module modules/mod_proxy_uwsgi.so
+
+Listen 8080
+
+<VirtualHost *:8080>
+ ProxyPass / uwsgi://127.0.0.1:35000/
+</VirtualHost>
+SSL is strongly recommended for security considerations. Refer to the specific web server +documentation on how to enable SSL.
+#systemctl start httpd.service
+Verify your settings after restart httpd servers (assume you are using above +configurations), if are you able to see similar output below, it means the zvmsdk +http service is running well.
+# curl http://localhost:8080/
+{"rs": 0, "overallRC": 0, "modID": null, "rc": 0, "output": {"min_version": "1.0", "version": "1.0", "max_version": "1.0"}, "errmsg": ""}
+The following packages need to be installed:
+apache2
libapache2-mod-wsgi
Create a vhost for Feilong in Apache. Copy the following content to +/etc/apache2/sites-available/zvmsdk_wsgi.conf and update the file to match your system and requirements.
+Then execute command “a2ensite zvmsdk_wsgi” to enable the site.
+Listen 8080
+<VirtualHost *:8080>
+ WSGIDaemonProcess zvmsdkwsgi user=zvmsdk group=zvmsdk processes=2 threads=5
+ WSGIProcessGroup zvmsdkwsgi
+
+ WSGIScriptAlias / /usr/bin/zvmsdk-wsgi
+ <Directory /usr/lib/python2.7/dist-packages/zvmsdk/sdkwsgi>
+ Require all granted
+ </Directory>
+
+ <Directory /usr/bin>
+ <Files zvmsdk-wsgi>
+ Require all granted
+ </Files>
+ </Directory>
+</VirtualHost>
+SSL is strongly recommended for security considerations. Refer to the specific web server +documentation on how to enable SSL.
+Start Apache service
+#systemctl start apache2.service
+Verify your settings after restart httpd servers (assume you are using above +configurations), if are you able to see similar output below, it means the zvmsdk +http service is running well.
+# curl http://localhost:8080/
+{"rs": 0, "overallRC": 0, "modID": null, "rc": 0, "output": {"min_version": "1.0", "version": "1.0", "max_version": "1.0"}, "errmsg": ""}
+When you sending requests, you can use token authenticaion to enhance security of the connection between client and server. +Feilong use admin-token to authicate the safety of the connection instead of username&password. +In other words, admin-token is what you can think as a combination of traditional username&password.
+On client side, users should use this admin-token to request for a temporary token first. Then users can use +this temporary token to send requests.
+On server side, admninistrators are responsible for creating admin-token file. The admin-token will be stored +in this file. Users can get admin-token by contacting administrator.
+Create admin-token file
+Administrators can use zvmsdk-gentoken tool to create admin-token file.
+Fox example, initialize one token file:
+# /usr/bin/zvmsdk-gentoken
+zvmsdk-gentoken use /etc/zvmsdk/token.dat as default path of token file. You can also specify your own token file path:
+# /usr/bin/zvmsdk-gentoken /new/path/of/token/file
+The commands above will initialize one token file and write a random admin-token into it.
+This tool can also help you update the content of token file:
+# /usr/bin/zvmsdk-gentoken -u
+If you don’t assign a file path, zvmsdk-gentoken will update the file of default token path. You can update specified +file by this way:
+# /usr/bin/zvmsdk-gentoken -u /new/path/of/token/file
+NOTE: please remember to change token file’s owner to user zvmsdk after operating it.
+Update Configuration file
+After creating admin-token file, configuration should be updated to let the server know the path of token file.
+In configuration file, you can assign token file path by change the value of token_path which is in wsgi section.
What’s more, you should let server know we have changed the way of authentication by setting value of auth item
+in the wsgi section to token, just like auth=token.
If you want to disable token authentication, just change auth to value none.
++On client side, you need to get the admin-token stored in the admin-token file. Just As what we have talked above, +admin-token file is generated on server side. Users should contact the administrator for admin-token before sending +requests. Then users can put the admin_token into the
+X-Admin-Tokenfield in headers of request object for +passing the authentication.An example to request for a token:
+++# curl http://localhost:8080/token -X POST -i -H "Content-Type:application/json" -H "X-Admin-Token:1234567890123456789012345678901234567890" +HTTP/1.0 200 OK +Date: Wed, 06 Dec 2017 06:11:22 GMT +Server: WSGIServer/0.1 Python/2.7.5 +Content-Type: text/html; charset=UTF-8 +Content-Length: 0 +X-Auth-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MTI1NDQyODJ9.TVlcQb_QuUPJ37cRyzZqroR6kLZ-5zH2-tliIkhsQ1A +cache-control: no-cache +You can see the temporary token is in the
+X-Auth-Tokenfield.Then you can send normal RESTful requests using this temporary token to pass the authentication.
+For example:
+++# curl http://localhost:8080/ -H "Content-Type:application/json" -H 'X-Auth-Token:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MTI1NDQyODJ9.TVlcQb_QuUPJ37cRyzZqroR6kLZ-5zH2-tliIkhsQ1A' +{"rs": 0, "overallRC": 0, "modID": null, "rc": 0, "output": {"min_version": "1.0", "version": "1.0", "max_version": "1.0"}, "errmsg": ""} +