Skip to content

Regenerated .rst files for all SM & SWU role docs #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
TaylorDigilio wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Regenerated .rst files for all SM & SWU role docs #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 126 additions & 0 deletions docs/source/roles/zmf_swmgmt_holds_for_reason.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@

:github_url: https://github.com/IBM/ibm_zosmf/tree/master/plugins/roles/zmf_swmgmt_holds_for_reason

.. _zmf_swmgmt_holds_for_reason_module:


zmf_swmgmt_holds_for_reason -- Collect ++HOLDs for selected REASON IDs
======================================================================


.. contents::
:local:
:depth: 1


Synopsis
--------
- The \ :strong:`IBM z/OSMF collection`\ provides an Ansible role, referred to as \ :strong:`zmf\_swmgmt\_holds\_for\_reason`\ , to separate SYSTEM HOLDs by REASON and prepare to query the CSI associated with a software instance. The SYSTEM HOLDs are gathered from the retrieve software update response and then the HOLDDATA text is gathered from the CSI query response.







Variables
---------




software_instance_uuid
A UUID of a software instance. A UUID is assigned to every software instance and can be obtained using the "List the software instances defined to z/OSMF" REST API.


A UUID can also be obtained using the zmf\_swmgmt\_zos\_system\_uuid Ansible role which retrieves the UUID for the software instance that represents the installed software for the specified z/OSMF host system.


A software instance UUID name must be specified.


This variable can be specified in the inventory file or as an argument on the playbook command.


| **required**: True
| **type**: str




hold_reason
The HOLD REASON ID for which to get the HOLDDATA text.


A HOLD REASON ID must be 1-7 characters long and is accepted in mixed case and is folded to uppercase automatically. It may consist of alphabetic, numeric, and national characters (@ \\# $).


This variable can be specified in the inventory file or as an argument on the playbook command.


| **required**: True
| **type**: str




holds_for_reason_dir
The directory that will contain the HOLDDATA text file. The directory specified must have valid UNIX directory name syntax. It must start and end with a slash ('/') and can be up to 1023 characters long.


One file will be written in this directory with the HOLDDATA text pertaining to the specified HOLD REASON each time this role is invoked. The file written will follow this naming convention where the file name will be the HOLD REASON: \ :literal:`YourHoldReason-HOLDDATA.txt`\


The directory must already exist otherwise there will be an error writing the results to the file. If files with the same name already exist in the directory, they will be overwritten by the new response when the playbook is executed. If files don't exist in the directory, they will be created.


This variable can be specified in the inventory file or as an argument on the playbook command.


| **required**: True
| **type**: str




Examples
--------

.. code-block:: yaml+jinja


- name: sample of separating HOLDs by REASON
hosts: sampleHost
gather_facts: no
collections:
- ibm.ibm_zosmf

tasks:
- include_role :
name: zmf_swmgmt_holds_for_reason




Notes
-----

.. note::
- The given example assumes you have an inventory file \ :emphasis:`inventory.yml`\ that contains the values for the two variables described above: software instance UUID and the HOLD REASON.


- Command syntax to call a playbook using an inventory file: \ :literal:`ansible-playbook -i inventory software\_management\_holds\_for\_reason\_CICDtest1.yml`\


- Command syntax to call a playbook using command arguments: \ :literal:`ansible-playbook software\_management\_holds\_for\_reason\_CICDtest1.yml -e software\_instance\_uuid=cccccc...444444 -e hold\_reason=ACTION -e holds\_for\_reason\_file=/Users/yourUser/AnsibleOutputDir/`\


- When the role is executed, a message shown in following example is displayed, \ :literal:`"msg": "Output filename= /tmp/xxx/ACTION-HOLDDATA.txt"`\ . This message includes a file path and file name where the HOLDDATA text for the requested HOLD REASON is returned.








29 changes: 25 additions & 4 deletions docs/source/roles/zmf_swupdate_cancel.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ zmf_swupdate_cancel -- Cancel a Software Update Process

Synopsis
--------
- The :strong:`IBM z/OSMF collection` provides an Ansible role, referred to as :strong:`zmf\_swupdate\_cancel`\ , cancels a software update process that is in progress on a software instance.
- The \ :strong:`IBM z/OSMF collection`\ provides an Ansible role, referred to as \ :strong:`zmf\_swupdate\_cancel`\ , cancels a software update process that is in progress on a software instance.




Expand All @@ -31,6 +32,7 @@ Variables
zmf_host
Hostname of the z/OSMF server, specified in the inventory file or as an argument on the playbook command.


| **required**: True
| **type**: str

Expand All @@ -40,6 +42,7 @@ zmf_host
zmf_port
Port number of the z/OSMF server. If z/OSMF is not using the default port, you need to specify a value for this parameter in the inventory file or as an argument on the playbook command.


| **required**: False
| **type**: str
| **default**: 443
Expand All @@ -52,6 +55,7 @@ zmf_user

This variable can be specified in the inventory file or as an argument on the playbook command.


| **required**: True
| **type**: str

Expand All @@ -63,6 +67,7 @@ zmf_password

This variable can be specified in the inventory file or as an argument on the playbook command.


| **required**: True
| **type**: str

Expand All @@ -72,10 +77,13 @@ zmf_password
software_instance_name
Name of the software instance for which the currently in progress software update process is cancelled.


A software instance name must be specified when a software instance UUID or a software update process ID are not specified. If a software update process ID is specified in addition to a software instance name and system nickname, then the software update process ID is used by default.


This variable can be specified in the inventory file or as an argument on the playbook command.


| **required**: False
| **type**: str

Expand All @@ -85,10 +93,13 @@ software_instance_name
system_nickname
Nickname of the z/OSMF host system that has access to the volumes and data sets where the software instance resides.


A system nickname must be specified when a software instance UUID or a software update process ID are not specified. If a software update process ID is specified in addition to a software instance name and system nickname, then the software update process ID is used by default.


This variable can be specified in the inventory file or as an argument on the playbook command.


| **required**: False
| **type**: str

Expand All @@ -98,12 +109,16 @@ system_nickname
software_instance_uuid
A UUID of a software instance for which the currently in progress software update process is cancelled. A UUID is assigned to every software instance and can be obtained using the "List the software instances defined to z/OSMF" REST API.


A UUID can also be obtained using the zmf\_swmgmt\_zos\_system\_uuid Ansible role which retrieves the UUID for the software instance that represents the installed software for the specified z/OSMF host system.


A software instance UUID must be specified when a software instance name or a software update process ID are not specified. If a software update process ID is specified in addition to a software instance UUID, then the software update process ID is used by default.


This variable can be specified in the inventory file or as an argument on the playbook command.


| **required**: False
| **type**: str

Expand All @@ -113,10 +128,13 @@ software_instance_uuid
swupdate_process_id
A software update process ID indicating the software update process to be canceled.


A software update process ID must be specified when a software instance name or a software instance UUID are not specified. If a process ID is specified in addition to a software instance name or UUID, then the process ID is used by default.


This variable can be specified in the inventory file or as an argument on the playbook command.


| **required**: False
| **type**: str

Expand Down Expand Up @@ -151,11 +169,14 @@ Notes
-----

.. note::
- The given example assumes you have an inventory file :emphasis:`inventory.yml` that contains the values for the variables described above, such as z/OSMF host server, userid, password, software instance name and system, and software update process ID.
- The given example assumes you have an inventory file \ :emphasis:`inventory.yml`\ that contains the values for the variables described above, such as z/OSMF host server, userid, password, software instance name and system, and software update process ID.


- Command syntax to call a playbook using an inventory file: \ :literal:`ansible-playbook -i inventory software\_management\_swu\_cancel\_CICDtest1.yml`\


- Command syntax to call a playbook using an inventory file: :literal:`ansible-playbook -i inventory software\_management\_swu\_cancel\_CICDtest1.yml`
- Command syntax to call a playbook using command arguments: \ :literal:`ansible-playbook software\_management\_swu\_cancel\_CICDtest1.yml -e zmf\_user=ibmuser -e zmf\_password=ibmuser -e software\_instance\_name=YourSwiName -e system\_nickname=YourSystemName`\

- Command syntax to call a playbook using command arguments: :literal:`ansible-playbook software\_management\_swu\_cancel\_CICDtest1.yml -e zmf\_user=ibmuser -e zmf\_password=ibmuser -e software\_instance\_name=YourSwiName -e system\_nickname=YourSystemName`



Expand Down
34 changes: 30 additions & 4 deletions docs/source/roles/zmf_swupdate_copy.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ zmf_swupdate_copy -- Copy a Software Update Process

Synopsis
--------
- The :strong:`IBM z/OSMF collection` provides an Ansible role, referred to as :strong:`zmf\_swupdate\_copy`\ , copies the output files from a software update process on a software instance.
- The \ :strong:`IBM z/OSMF collection`\ provides an Ansible role, referred to as \ :strong:`zmf\_swupdate\_copy`\ , copies the output files from a software update process on a software instance.




Expand All @@ -31,6 +32,7 @@ Variables
zmf_host
Hostname of the z/OSMF server, specified in the inventory file or as an argument on the playbook command.


| **required**: True
| **type**: str

Expand All @@ -40,6 +42,7 @@ zmf_host
zmf_port
Port number of the z/OSMF server. If z/OSMF is not using the default port, you need to specify a value for this parameter in the inventory file or as an argument on the playbook command.


| **required**: False
| **type**: str
| **default**: 443
Expand All @@ -52,6 +55,7 @@ zmf_user

This variable can be specified in the inventory file or as an argument on the playbook command.


| **required**: True
| **type**: str

Expand All @@ -63,6 +67,7 @@ zmf_password

This variable can be specified in the inventory file or as an argument on the playbook command.


| **required**: True
| **type**: str

Expand All @@ -72,10 +77,13 @@ zmf_password
software_instance_name
Name of the software instance for which the saved output files for the most recent software update process are copied.


A software instance name must be specified when a software instance UUID or a software update process ID are not specified. If a software update process ID is specified in addition to a software instance name and system nickname, then the software update process ID is used by default.


This variable can be specified in the inventory file or as an argument on the playbook command.


| **required**: False
| **type**: str

Expand All @@ -85,10 +93,13 @@ software_instance_name
system_nickname
Nickname of the z/OSMF host system that has access to the volumes and data sets where the software instance resides.


A system nickname must be specified when a software instance UUID or a software update process ID are not specified. If a software update process ID is specified in addition to a software instance name and system nickname, then the software update process ID is used by default.


This variable can be specified in the inventory file or as an argument on the playbook command.


| **required**: False
| **type**: str

Expand All @@ -98,12 +109,16 @@ system_nickname
software_instance_uuid
A UUID of a software instance for which the saved output files for the most recent software update process are copied. A UUID is assigned to every software instance and can be obtained using the "List the software instances defined to z/OSMF" REST API.


A UUID can also be obtained using the zmf\_swmgmt\_zos\_system\_uuid Ansible role which retrieves the UUID for the software instance that represents the installed software for the specified z/OSMF host system.


A software instance UUID must be specified when a software instance name or a software update process ID are not specified. If a software update process ID is specified in addition to a software instance UUID, then the software update process ID is used by default.


This variable can be specified in the inventory file or as an argument on the playbook command.


| **required**: False
| **type**: str

Expand All @@ -113,10 +128,13 @@ software_instance_uuid
swupdate_process_id
A software update process ID indicating the software update process whose saved output files will be copied.


A software update process ID must be specified when a software instance name or a software instance UUID are not specified. If a process ID is specified in addition to a software instance name or UUID, then the process ID is used by default.


This variable can be specified in the inventory file or as an argument on the playbook command.


| **required**: False
| **type**: str

Expand All @@ -126,10 +144,13 @@ swupdate_process_id
directory
The absolute file system directory into which the saved output files will be copied. The directory value should be url-encoded.


If the directory does not exist, then Sofware Update will create it. If the directory already exists, then Software Update will append (x), where x is the next available integer, to the specified directory name and create it.


This variable can be specified in the inventory file or as an argument on the playbook command.


| **required**: True
| **type**: str

Expand All @@ -141,8 +162,10 @@ swupdate_copy_response_file

The directory must already exist otherwise there will be an error writing the results to the file. If the file exists in the directory already, it will be overwritten by the new response when the playbook is executed. If the file doesn't exist in the directory, it will be created.


This variable can be specified in the inventory file or as an argument on the playbook command.


| **required**: True
| **type**: str

Expand Down Expand Up @@ -178,11 +201,14 @@ Notes
-----

.. note::
- The given example assumes you have an inventory file :emphasis:`inventory.yml` that contains the values for the variables described above, such as z/OSMF host server, userid, password, software instance name and system, and software update process ID.
- The given example assumes you have an inventory file \ :emphasis:`inventory.yml`\ that contains the values for the variables described above, such as z/OSMF host server, userid, password, software instance name and system, and software update process ID.


- Command syntax to call a playbook using an inventory file: \ :literal:`ansible-playbook -i inventory software\_management\_swu\_start\_and\_resolve\_all\_system\_holds\_CICDtest1.yml`\


- Command syntax to call a playbook using an inventory file: :literal:`ansible-playbook -i inventory software\_management\_swu\_start\_and\_resolve\_all\_system\_holds\_CICDtest1.yml`
- Command syntax to call a playbook using command arguments: \ :literal:`ansible-playbook software\_management\_swu\_start\_and\_resolve\_all\_system\_holds\_CICDtest1.yml -e zmf\_user=ibmuser -e zmf\_password=ibmuser -e software\_instance\_name=YourSwiName -e system\_nickname=YourSystemName -e directory=/u/ibmuser/yourDirName/ -e swupdate\_retrieve\_response\_file=/Users/yourUser/AnsibleOutputDir/YourSwiNameRetrieve.json`\

- Command syntax to call a playbook using command arguments: :literal:`ansible-playbook software\_management\_swu\_start\_and\_resolve\_all\_system\_holds\_CICDtest1.yml -e zmf\_user=ibmuser -e zmf\_password=ibmuser -e software\_instance\_name=YourSwiName -e system\_nickname=YourSystemName -e directory=/u/ibmuser/yourDirName/ -e swupdate\_retrieve\_response\_file=/Users/yourUser/AnsibleOutputDir/YourSwiNameRetrieve.json`



Expand Down
Loading