diff --git a/check-oracle.sh b/check-oracle.sh new file mode 100755 index 00000000..5adbd342 --- /dev/null +++ b/check-oracle.sh @@ -0,0 +1,229 @@ +#!/bin/bash +# Copyright 2025 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# used for oracle ORAchk. install, run and uninstall ORAchk +# +# Check if we're using the Mac stock getopt and fail if true +# shellcheck disable=SC2034 +out="$(getopt -T)" +if [ $? != 4 ]; then + echo -e "Your getopt does not support long parameters, possibly you're on a Mac, if so please install gnu-getopt with brew" + echo -e "\thttps://brewformulas.org/Gnu-getopt" + exit 1 +fi + +# do not display skipped hosts - +# a misnomer, as it does not display all 'skipped' tasks +export ANSIBLE_EXTRA_VARS='' +# use ANSIBLE_DISPLAY_SKIPPED_HOSTS=true ./check-oracle.sh to see skipped tasks +: ${ANSIBLE_DISPLAY_SKIPPED_HOSTS:=false} +export ANSIBLE_DISPLAY_SKIPPED_HOSTS +#echo ANSIBLE_DISPLAY_SKIPPED_HOSTS: $ANSIBLE_DISPLAY_SKIPPED_HOSTS + +export INVENTORY_FILE='' +export AHF_LOCATION='' + +export AHF_LOCATION_PARAM='^gs://.+[^/]$' + +export ORACLE_SERVER='' +export AHF_DIR='AHF' +export AHF_FILE='' +export AHF_INSTALL=0 +export AHF_UNINSTALL=0 +export RUN_ORACHK=0 + +export GETOPT_MANDATORY="instance-ip-addr:" +export GETOPT_OPTIONAL="extra-vars:,ahf-location:,db-name:,inventory-file:,ahf-install,ahf-uninstall,run-orachk,help,debug" + +export GETOPT_LONG="$GETOPT_MANDATORY,$GETOPT_OPTIONAL" +export GETOPT_SHORT="h" + +options="$(getopt --longoptions "$GETOPT_LONG" --options "$GETOPT_SHORT" -- "$@")" + +# shellcheck disable=SC2181 +[ $? -eq 0 ] || { + echo "Invalid options provided: $*" >&2 + exit 1 +} + +eval set -- "$options" + +help () { + + echo -e "\tUsage: $(basename "$0")" + echo "${GETOPT_MANDATORY}" | sed 's/,/\n/g' | sed 's/:/ /' | sed 's/\(.\+\)/\t --\1/' + echo "${GETOPT_OPTIONAL}" | sed 's/,/\n/g' | sed 's/:/ /' | sed 's/\(.\+\)/\t [ --\1 ]/' + echo + echo "--ahf-install and --run-orachk may be combined to install and run" + echo "--extra-vars is used to pass extra ansible vars" + echo " example: --extra-vars "var1=val1 var2=val2 ..."" + +} + +# check if both install and run were specified together +export RUN_ENABLED=0 +export INSTALL_ENABLED=0 + +while true +do + + case "$1" in + + --extra-vars) + ANSIBLE_EXTRA_VARS="$2" + ;; + + --ahf-location) + AHF_LOCATION="$2" + ;; + + --debug) + export ANSIBLE_DEBUG=1 + export ANSIBLE_DISPLAY_SKIPPED_HOSTS=true + ;; + + --help | -h) + help >&2 + exit 0 + ;; + + --inventory-file) + INVENTORY_FILE="$2" + shift; + ;; + + --db-name) + ORACLE_SID="$2" + shift + ;; + + --instance-ip-addr) + ORACLE_SERVER="$2" + shift + ;; + + --ahf-install) + : ${ORACLE_SID:='NOOP'} + AHF_UNINSTALL=1 + AHF_INSTALL=1 + INSTALL_ENABLED=1 + ;; + + --ahf-uninstall) + ORACLE_SID='NOOP' + AHF_UNINSTALL=1 + AHF_INSTALL=0 + ;; + + --run-orachk) + AHF_UNINSTALL=0 + AHF_INSTALL=0 + RUN_ORACHK=1 + RUN_ENABLED=1 + ;; + + --) + shift + break + ;; + + esac + + shift + +done + +# one of install, uninstall or run must be called + +[[ $AHF_INSTALL -eq 0 ]] && [[ $AHF_UNINSTALL -eq 0 ]] && [[ $RUN_ORACHK -eq 0 ]] && { help; exit 1; } + + +[[ -n $ANSIBLE_EXTRA_VARS ]] && { + + if [[ ! "$ANSIBLE_EXTRA_VARS" =~ ^([a-zA-Z_][a-zA-Z0-9_]*=[^[:space:]]+)([[:space:]]+[a-zA-Z_][a-zA-Z0-9_]*=[^[:space:]]+)*$ ]]; then + echo "Invalid format for --extra-vars" + echo "the extra vars should be a string of 1 or more name=value pairs separated by a space" + echo "example: varname1=value varname2=value2 varname3=value3" + exit 1 + fi + +} + +[ "$RUN_ENABLED" -eq 1 ] && [ "$INSTALL_ENABLED" -eq 1 ] && { + AHF_UNINSTALL=1 + AHF_INSTALL=1 + INSTALL_ENABLED=1 +} + +[[ -z $ORACLE_SID ]] && { echo "please specify --db-name"; echo; help; exit 1; } + +# if an ip address is passed for --instance-ip-address, and inventory file is not specified on the cli, check for an inventory file by lookup of target hostname +[[ "$ORACLE_SERVER" =~ ^[[:digit:]]{1,3}[.][[:digit:]]{1,3}[.][[:digit:]]{1,3}[.][[:digit:]]{1,3}$ ]] && [[ -z "$INVENTORY_FILE" ]] && { + TARGET_HOSTNAME="$( dig +short -x $ORACLE_SERVER | cut -f1 -d\. )" + TEST_INVENTORY_FILE=inventory_files/inventory_${TARGET_HOSTNAME}_${ORACLE_SID} + [[ -r $TEST_INVENTORY_FILE ]] && INVENTORY_FILE="$TEST_INVENTORY_FILE" +} + +# if the inventory file is specified on the cli, then the --instance-ip-addr or ORACLE_SERVER are not required +if [[ -z $INVENTORY_FILE ]]; then + [[ -z $ORACLE_SERVER ]] && { echo "please specify --instance-ip-addr"; echo; help; exit 1; } + INVENTORY_FILE=inventory_files/inventory_${ORACLE_SERVER}_${ORACLE_SID} +fi + +[[ -r $INVENTORY_FILE ]] || { + echo "cannot read inventory file '$INVENTORY_FILE'" + echo " please check and --instance-ip-addr" + echo " and --inventory-file" + exit 1 +} + +# fail early if the AFH file format is incorrect and/or the file does not exist. +[[ -n "$AHF_LOCATION" ]] || [[ $AHF_INSTALL -eq 1 ]] && { + + [[ ! "$AHF_LOCATION" =~ $AHF_LOCATION_PARAM ]] && { + echo "Incorrect parameter provided for AHF_LOCATION: $AHF_LOCATION" + echo "Example: gs://my-gcs-bucket/ahf/ahf.zip" + exit 1 + } + + ( gsutil ls "$AHF_LOCATION" >/dev/null 2>&1 ) || { + echo "--ahf-location file '$AHF_LOCATION' not found" + exit 1; + } +} + +# Uninstall AHF +[[ $AHF_UNINSTALL -eq 1 ]] && { + + ansible-playbook -i "$INVENTORY_FILE" check-oracle.yml \ + --extra-vars "uninstall_ahf=true $ANSIBLE_EXTRA_VARS" +} + +# Install AHF +[[ $AHF_INSTALL -eq 1 ]] && { + + + ansible-playbook -i "$INVENTORY_FILE" check-oracle.yml \ + --extra-vars "uninstall_ahf=false AHF_LOCATION=$AHF_LOCATION $ANSIBLE_EXTRA_VARS" +} + +# run ORAchk +[[ $RUN_ORACHK -eq 1 ]] && { + + ansible-playbook -i "$INVENTORY_FILE" check-oracle.yml \ + --extra-vars "uninstall_ahf=false run_orachk=true ORACLE_SID=$ORACLE_SID $ANSIBLE_EXTRA_VARS" +} + + diff --git a/check-oracle.yml b/check-oracle.yml new file mode 100644 index 00000000..c1d89370 --- /dev/null +++ b/check-oracle.yml @@ -0,0 +1,327 @@ +# Copyright 2025 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +--- +# check-oracle.yml +- name: "ORAchk: uninstall, install or run" + hosts: all + gather_facts: false + roles: + - role: check-oracle + + tasks: + + - name: Check for AHF Installation + stat: + path: "{{ AHFCTL_PATH }}" + register: ahfctl_script + + + - block: + - name: Uninstall AHF + become: true + shell: yes 'Y' | "{{ AHFCTL_PATH }}" uninstall + ignore_errors: true + failed_when: ahf_uninstall_result.rc != 0 and ahf_uninstall_result.rc is defined + register: ahf_uninstall_result + + - name: Remove AHF Unzip Location + become: true + file: + path: "{{ ahf_extract_path }}" + state: absent + + - name: Remove orachk directory + become: true + file: + path: "{{ orachk_script_dir }}" + state: absent + + - name: Remove orachk base directory + become: true + file: + path: "{{ ORACHK_BASE }}" + state: absent + + when: (uninstall_ahf | bool) + + - block: + - name: Create AHF directory + become: true + file: + path: "{{ ahf_extract_path }}" + state: directory + mode: "0700" + + - name: Create ORAchk directory + become: true + file: + path: "{{ orachk_script_dir }}" + state: directory + mode: "0700" + + - name: Copy AHF file from Google Storage + become: false + vars: + local_ahf_path: "/tmp/{{ AHF_LOCATION | basename }}" + + block: + + # leave these here for testing + # this has been a problem area + #- name: Local AHF File + #debug: + #msg: "AHF File Source: {{ local_ahf_path }}" + + #- name: Remote AHF File Dest + #debug: + #msg: "AHF File Dest: {{ ahf_extract_path }}/{{ AHF_LOCATION | basename }}" + + - name: Download AHF file from Google Storage to the ansible control node. + become: false + local_action: + module: command + cmd: gcloud storage cp --verbosity=debug "{{ AHF_LOCATION }}" "{{ local_ahf_path }}" + register: gsutil_result + changed_when: gsutil_result.rc == 0 + + - name: Check if {{ local_ahf_path }} exists + become: false + stat: + path: "{{ local_ahf_path }}" + register: file_status_check + delegate_to: localhost + + - name: File Status + become: false + debug: + msg: "file exists" + when: file_status_check.stat.exists + + - name: Fail if the file does not exist + become: false + fail: + msg: "File {{ local_ahf_path }} does not exist." + when: not file_status_check.stat.exists + + - name: Copy AHF file to remote host if it is a zip file. + become: true + copy: + src: "{{ local_ahf_path }}" + dest: "{{ ahf_extract_path }}/{{ AHF_LOCATION | basename }}" + when: file_status_check.stat.exists + + - name: remove local AHF file. + become: false + file: + path: "{{ local_ahf_path }}" + state: absent + delegate_to: localhost + + - name: Get status of remote zip + become: true + stat: + path: "{{ ahf_extract_path }}/{{ AHF_LOCATION | basename }}" + register: remote_zip_status + + - name: Fail if Zip not found "{{ ahf_extract_path }}/{{ AHF_LOCATION | basename }}" + become: true + fail: + msg: "File {{ ahf_extract_path }}/{{ AHF_LOCATION | basename }} does not exist" + when: not remote_zip_status.stat.exists + + - name: Unzip AHF file + become: true + unarchive: + src: "{{ ahf_extract_path }}/{{ AHF_LOCATION | basename }}" + dest: "{{ ahf_extract_path }}" + remote_src: true + + - name: Verify AHF setup signature + become: true + shell: openssl dgst -sha256 -verify ./oracle-tfa.pub -signature ./ahf_setup.dat ./ahf_setup + args: + chdir: "{{ ahf_extract_path }}" + + - name: Ensure perl is installed + become: true + package: + name: perl + state: present + + - name: Run AHF setup + become: true + shell: yes 'Y' | ./ahf_setup -extract -notfasetup + args: + chdir: "{{ ahf_extract_path }}" + when: ( not ( uninstall_ahf | bool ) ) and ( not ( run_orachk | bool ) ) + + - block: + + - name: Copy login.sql file to target system + become: true + copy: + src: roles/check-oracle/files/login.sql + dest: "{{ orachk_script_dir }}/login.sql" + owner: root + group: root + mode: '0600' + + - name: Copy orachk-quicktest.sh for expedited testing + become: true + copy: + src: roles/check-oracle/files/orachk-quicktest.sh + dest: "{{ ORACHK_BASE }}/orachk/orachk-quicktest.sh" + owner: root + group: root + mode: '0700' + when: ( expedited_testing | bool ) + + - name: Configure Expedited Testing + become: true + shell: cd "{{ ORACHK_BASE }}/orachk/" && [[ ! -r orachk.orig ]] && mv orachk orachk.orig && ln -s orachk-quicktest.sh orachk + when: ( expedited_testing | bool ) + + - name: Check for oratab + stat: + path: "{{ oratab_path }}" + register: oratab_exists + + - name: oratab not found + fail: + msg: "The file {{ oratab_path }} was not found on the target" + when: not ( oratab_exists.stat.exists | bool ) + + - name: Slurp oratab from remote + slurp: + src: "{{ oratab_path }}" + register: oratab_contents + + - name: Split oratab file contents into lines + set_fact: + oratab_lines: "{{ oratab_contents.content | b64decode | split('\n') }}" + + - name: Check for ORACLE_SID + shell: "grep ^{{ ORACLE_SID }} {{ oratab_path }}" + register: oratab_results + ignore_errors: true + + - name: ORACLE_HOME Not Found + fail: + msg: "ORACLE_HOME was not found on the target for {{ ORACLE_SID }}" + when: oratab_results.rc != 0 + + - name: Parse oratab to find Oracle Home for {{ ORACLE_SID }} + set_fact: + ORACLE_HOME: >- + {{ + (oratab_lines + | select('match', '^' ~ ORACLE_SID ~ ':') + | list + | first + ).split(':')[1] + }} + when: oratab_lines is defined and (oratab_lines | length) > 0 + failed_when: oratab_lines is not defined + + - name: Display ORACLE_HOME + debug: + msg: "Found ORACLE_HOME={{ ORACLE_HOME }}" + + - name: Get a tmpfile name + set_fact: + TMPFILE: "{{ lookup('pipe','mktemp -t orachk.XXXXXX') }}" + + # create a temporary log file from the orachk run + # this can be used the location of the zip file created by ORAchk + - name: Run ORAchk + become: true + shell: "ORACLE_PATH={{ orachk_script_dir }} SQLPATH={{ orachk_script_dir }} {{ ORACHK_BASE }}/orachk/orachk -s -dbconfig {{ ORACLE_HOME }}%{{ ORACLE_SID }} -showpass -profile dba | tee {{ TMPFILE }}" + environment: + ORACLE_SID: "{{ ORACLE_SID }}" + PATH: "{{ extended_path }}" + args: + chdir: "{{ orachk_script_dir }}" + + - name: Get ORAchk tmpfile status + stat: + path: "{{ TMPFILE }}" + register: tmpfile_location + + - name: Check that ORAchk tmpfile exists + fail: + msg: "Could not find ORAchk tmpfile {{ TMPFILE }}" + when: not tmpfile_location.stat.exists + + - name: Retrieve ORAchk zipfile name from tmpfile + shell: "grep UPLOAD {{ TMPFILE }} | awk '{ print $NF }'" + register: orachk_file_info + + - name: Get a tmpfile name + set_fact: + ORACHK_RPT_FILE: "{{ orachk_file_info.stdout }}" + + - name: Verify ORAchk Report File Existence + become: true + stat: + path: "{{ ORACHK_RPT_FILE }}" + register: orachk_rpt_location + + - name: Was ORAchk report name found + fail: + msg: "Could not locate ORAchk report file {{ ORACHK_RPT_FILE }}" + when: not orachk_rpt_location.stat.exists + + - name: Create /tmp/orachk directory for the zip files + become: false + file: + path: /tmp/orachk/ + state: directory + mode: "0700" + + - name: Fetch the ORAchk zipfile + become: true + fetch: + src: "{{ ORACHK_RPT_FILE }}" + dest: /tmp/orachk/ + flat: true + register: fetch_result + + - name: Remove temporary file on controller + file: + path: "{{ TMPFILE }}" + state: absent + delegate_to: localhost + when: TMPFILE is defined + + - name: Deconfigure Expedited Testing + become: true + shell: cd "{{ ORACHK_BASE }}/orachk/" && [[ -r orachk.orig ]] && rm -f orachk && mv orachk.orig orachk && rm -f orachk-quicktest.sh + when: ( expedited_testing | bool ) + + # See what was actually returned by the fetch task + # this will be useful if the ansible version changes + # - name: Debug the entire fetch_result + # debug: + # var: fetch_result + + # Only display the path if it exists in fetch_result.files + - name: Display local path of fetched file + debug: + msg: "Fetched file is saved locally at: {{ fetch_result.files[0].dest }}" + when: fetch_result.files is defined and (fetch_result.files | length) > 0 + + - name: Display local path of fetched file + debug: + msg: "Fetched file is saved locally at: {{ fetch_result.dest }}" + when: ( not ( uninstall_ahf | bool ) ) and ( run_orachk | bool ) diff --git a/docs/user-guide.md b/docs/user-guide.md index fefe5ccf..345f8f02 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -17,7 +17,7 @@ published: True - [Requirements and Prerequisites](#requirements-and-prerequisites) - [Control node requirements](#control-node-requirements) - [Target server requirements](#target-server-requirements) - - [Installing the toolkit](#installing-the-toolkit) + - [Installing the oracle-toolkit](#installing-the-oracle-toolkit) - [Downloading and staging the Oracle Software](#downloading-and-staging-the-oracle-software) - [Downloading the Oracle installation software](#downloading-the-oracle-installation-software) - [Downloading Patches from My Oracle Support](#downloading-patches-from-my-oracle-support) @@ -48,8 +48,9 @@ published: True - [Oracle Database Free Edition Specific Details and Changes](#oracle-database-free-edition-specific-details-and-changes) - [Free Edition Version Details](#free-edition-version-details) - [Sample Invocations for Oracle Database Free Edition](#sample-invocations-for-oracle-database-free-edition) - - [Example Toolkit Execution for Free Edition](#example-toolkit-execution-for-free-edition) + - [Example Oracle Toolkit Execution for Free Edition](#example-oracle-toolkit-execution-for-free-edition) - [Post installation tasks](#post-installation-tasks) + - [Validate the Oracle installation with ORAchk](#validate-the-oracle-installation-with-orachk) - [Reset passwords](#reset-passwords) - [Validate the environment](#validate-the-environment) - [Listing Oracle ASM devices](#listing-oracle-asm-devices) @@ -64,9 +65,9 @@ published: True ## Command quick reference for single instance deployments -Sample commands for a simple quick-start and basic toolkit usage for an Oracle +Sample commands for a simple quick-start and basic oracle-toolkit usage for an Oracle "single instance" database. Refer to the remainder of this document for -additional details and comprehensive explanations of the toolkit, scripting, +additional details and comprehensive explanations of the oracle-toolkit, scripting, options, and usage scenarios. All commands run from the "control node". 1. Validate media specifying GCS storage bucket and optionally database: @@ -83,7 +84,7 @@ options, and usage scenarios. All commands run from the "control node". ssh ${INSTANCE_SSH_USER:-`whoami`}@${INSTANCE_IP_ADDR} sudo -u root hostname ``` -1. Review toolkit parameters: +1. Review oracle-toolkit parameters: ```bash ./install-oracle.sh --help @@ -120,7 +121,7 @@ Initial steps similar to those of the Single Instance installation. ssh ${INSTANCE_SSH_USER:-`whoami`}@${INSTANCE_IP_ADDR_NODE_2} sudo -u root hostname ``` -1. Review optional toolkit parameters: +1. Review optional oracle-toolkit parameters: `./install-oracle.sh --help` @@ -167,7 +168,7 @@ To create a standby database, add the following options to the command options t ## Command quick reference for Oracle Database Free Edition deployments -The toolkit supports installing the Oracle Database Free edition, which is downloadable from the Oracle website: [Oracle Database Free Get Started](https://www.oracle.com/database/free/get-started/). +The oracle-toolkit supports installing the Oracle Database Free edition, which is downloadable from the Oracle website: [Oracle Database Free Get Started](https://www.oracle.com/database/free/get-started/). Unlike with other Oracle Database editions, the Free edition is available in [RPM package](https://en.wikipedia.org/wiki/RPM_Package_Manager) format only. Consequently, the associated Enterprise Linux pre-installation and database RPM files must be downloaded and staged in the GCS storage bucket. @@ -185,7 +186,7 @@ Unlike with other Oracle Database editions, the Free edition is available in [RP ssh ${INSTANCE_SSH_USER:-`whoami`}@${INSTANCE_IP_ADDR} sudo -u root hostname ``` -1. Review toolkit parameters: +1. Review oracle-toolkit parameters: ```bash ./install-oracle.sh --help @@ -213,6 +214,7 @@ This guide is for experienced professional users of Oracle software who are deploying Oracle Database software and preparing initial Oracle databases on Google Cloud [Bare Metal Solution](https://cloud.google.com/bare-metal), or on Google Cloud [Compute Engine](https://cloud.google.com/products/compute) . + The toolkit defines default values for most options, so you can run the toolkit with only a few specifications. Your configuration options are listed later in this guide. @@ -229,17 +231,17 @@ RUs: - Oracle 21c - Oracle 23ai (currently [Free Edition](#oracle-database-free-edition-specific-details-and-changes)) -The toolkit does not include any Oracle software. You must obtain the +The oracle-toolkit does not include any Oracle software. You must obtain the appropriate licenses and download the Oracle software on your own. This guide provides information about where to obtain Oracle software solely for your convenience. After downloading the Oracle software, you stage the software in a Cloud Storage -bucket where the toolkit can access it. +bucket where the oracle-toolkit can access it. ### Software Stack -The toolkit customizes the software stack for Oracle Database workloads. Any out +The oracle-toolkit customizes the software stack for Oracle Database workloads. Any out of a number of Oracle Database software releases can be installed. In addition, the configuration of the software stack includes: @@ -268,9 +270,9 @@ You can further customize the environment and host server(s), as needed. ### Requirements and Prerequisites -You need at least two servers to install Oracle software by using the toolkit: +You need at least two servers to install Oracle software by using the oracle-toolkit: -- **Control node**: a virtual or physical machine from which the toolkit is +- **Control node**: a virtual or physical machine from which the oracle-toolkit is executed. - **Database server(s)**: target where the Oracle software will be installed and configured. @@ -294,7 +296,7 @@ The control node can be any server capable of ssh. The control node must have the following software installed: -- [Ansible](https://en.wikipedia.org/wiki/Ansible_(software)) +- [Ansible]() version 2.9 or higher. - If you are using a Cloud Storage bucket to stage your Oracle installation media, the [Google Cloud SDK](https://cloud.google.com/sdk/docs). @@ -312,14 +314,14 @@ of Cloud SDK is installed for you. #### Target server requirements -Prior to running the toolkit, ensure that the control node has SSH access to a +Prior to running the oracle-toolkit, ensure that the control node has SSH access to a Linux user account on the target server. The user account must have elevated security privileges, such as granted by "sudo su -", to install and configure -Oracle software. The toolkit creates _Oracle software owners_, such as `oracle` +Oracle software. The oracle-toolkit creates _Oracle software owners_, such as `oracle` and `grid`. The target database server(s) must be running a version of Linux that is -certified for Oracle Database. The toolkit currently supports the following +certified for Oracle Database. The oracle-toolkit currently supports the following certified OS versions: - Red Hat Enterprise Linux (RHEL) 7 and 8 (versions 7.3 and up). @@ -329,7 +331,12 @@ For more information about Oracle-supported platforms see the Oracle certification matrix in the "My Oracle Support" (MOS) site (sign in required): [https://support.oracle.com](https://support.oracle.com). -## Installing the toolkit +## Installing the oracle-toolkit + +<<<<<<< HEAD +The latest version of the oracle-toolkit can be downloaded from Google Git +Repositories: +[https://github.com/google/oracle-toolkit](https://github.com/google/oracle-toolkit) The latest version of the toolkit can be downloaded from Google Git Repositories: https://github.com/google/oracle-toolkit @@ -344,7 +351,7 @@ $HOME directory. ## Downloading and staging the Oracle Software You must download and stage the Oracle software yourself, in accordance with the -applicable licenses governing such software. The toolkit doesn't contain any +applicable licenses governing such software. The oracle-toolkit doesn't contain any Oracle software. You are responsible for procuring the Oracle software that you need and for complying with the applicable licenses. @@ -372,12 +379,12 @@ below. Before you download Oracle software and patches, review and acknowledge Oracle's license terms. -Before using the toolkit, download all of the software pieces for your Oracle +Before using the oracle-toolkit, download all of the software pieces for your Oracle release, including the base release, patch sets, the OPatch utility, and any additional patches listed by Oracle (unless using `--no-patch`, at which point only the base release is installed). -Do not unzip the downloaded installation files. The toolkit requires the +Do not unzip the downloaded installation files. The oracle-toolkit requires the downloads in their original, compressed-file format. #### Downloading Patches from My Oracle Support @@ -1018,7 +1025,7 @@ href="https://support.oracle.com/epmos/faces/PatchResultsNDetails?releaseId=8011 If the required software components are not properly downloaded and staged, the -toolkit will fail. +oracle-toolkit will fail. ### Staging the Oracle installation media @@ -1061,7 +1068,7 @@ You can then pass the file as a parameter to the deployment: --ora-swlib-type gcsfuse --ora-swlib-bucket oracle-swlib --ora-swlib-credentials ~/path_to/service_account.json ``` -The toolkit uploads the service account to the server so that Cloud Storage FUSE +The oracle-toolkit uploads the service account to the server so that Cloud Storage FUSE can use it. #### NFS share @@ -1175,7 +1182,7 @@ Specify the block devices (actual devices, not partitions), the mount point names, the file system types, and the mount options in valid JSON format. -When you run the toolkit, specify the path to the configuration file by using +When you run the oracle-toolkit, specify the path to the configuration file by using either the `--ora-data-mounts` command line option or the `ORA_DATA_MOUNTS` environment variable. The file path can be relative or fully qualified. The file name defaults to `data_mounts_config.json`. @@ -1211,7 +1218,7 @@ In the ASM disk group configuration, specify the disk group names, the disk names, and the associated block devices (the actual devices, not partitions) in a valid JSON format. -When you run the toolkit, specify the path to the configuration file by using +When you run the oracle-toolkit, specify the path to the configuration file by using either the `--ora-asm-disks` command line option or the `ORA_ASM_DISKS` environment variable. The file path can be relative or fully qualified. The file name defaults to `ask_disk_config.json`. Alternatively, pass the file content directly @@ -1253,9 +1260,9 @@ using the following format: ## Configuring Installations -You run the toolkit by using the `install-oracle.sh` shell script. +You run the oracle-toolkit by using the `install-oracle.sh` shell script. -**IMPORTANT**: From the control node, run the toolkit shell scripts by using a +**IMPORTANT**: From the control node, run the oracle-toolkit shell scripts by using a Linux user account that has the necessary SSH permissions and privileges on the target database server(s). @@ -1263,21 +1270,21 @@ You need to specify the Cloud Storage bucket that contains the Oracle software and the backup destination for an initial RMAN backup. Running with the --help argument displays the list of available options. -Although the toolkit provides defaults for just about everything, in most cases, +Although the oracle-toolkit provides defaults for just about everything, in most cases, you need to customize your installation to some degree. Your customizations can range from simple items, such as the name of a database or the associated database edition, to less frequently adjusted items, such as ASM disk groups configurations. Regardless, the toolkit allows you to specify overrides for most configuration parameters. -As well as creating the initial database, the toolkit implements and schedules a +As well as creating the initial database, the oracle-toolkit implements and schedules a simple RMAN backup script. You can adjust the backup parameters either before or -after running the toolkit, as required. +after running the oracle-toolkit, as required. ### Configuration defaults Most parameters have default values, so you only need to specify them when you -need a different value. The parameter values that the toolkit uses are echoed +need a different value. The parameter values that the oracle-toolkit uses are echoed during execution so you can confirm the configuration. The complete list of parameters and their values are provided in the [Parameters @@ -1290,7 +1297,7 @@ The Oracle convention for naming of file system mounts is **_/pm_**, where integer. The standard string constant for Oracle user file system mounts is the letter "u". -Following this convention, the toolkit creates the following default file system +Following this convention, the oracle-toolkit creates the following default file system mounts: - **/u01** - For Oracle software. For example, /u01/app/oracle/product. @@ -1304,13 +1311,13 @@ for the software staging and other purposes. You can use the single file system, ### Database backup configuration -As a part of installation, the toolkit creates an initial RMAN full database +As a part of installation, the oracle-toolkit creates an initial RMAN full database backup, an archived redo log backup, and sets the initial backup schedule based on your specifications or the default backup values. The parameters for configuring your backups are described in [Backup configuration parameters](#backup-configuration-parameters). The following list shows the -default backup configuration implemented by the toolkit: +default backup configuration implemented by the oracle-toolkit: - Backup scripts are stored in the directory `/home/oracle/scripts`. - Associated log files are stored in the directory `/home/oracle/logs`. @@ -1320,7 +1327,7 @@ default backup configuration implemented by the toolkit: - Hourly archived redo log backups run at 30 minutes past every hour. - RMAN backups are written to the Fast Recovery Area (FRA). -The toolkit schedules the backups by using the Linux cron utility under the +The oracle-toolkit schedules the backups by using the Linux cron utility under the Oracle software owner user. You can run the backup scripts as necessary. After installation is complete, you can adjust any of the attributes of the @@ -1428,8 +1435,8 @@ No environment variable

user defined
-toolkit generated -Optional Ansible inventory file name. If not supplied, the toolkit +oracle-toolkit generated +Optional Ansible inventory file name. If not supplied, the oracle-toolkit generates a filename. @@ -2376,11 +2383,11 @@ However, Oracle Database "Free Edition" has a number of differences, including: 1. Requires that the [Oracle Database Preinstallation RPM](https://docs.oracle.com/en/database/oracle/oracle-database/23/ladbi/about-the-oracle-preinstallation-rpm.html) be installed as it is a dependent package. 1. Has CPU, memory, and user-data storage limits – see [Oracle Database Free FAQ – Installation](https://www.oracle.com/database/free/faq/#installation) for details. -Similar to with the other editions, creation of an initial database and implementation of RMAN based backups is possible through this toolkit for Oracle Database free edition. +Similar to with the other editions, creation of an initial database and implementation of RMAN based backups is possible through this oracle-toolkit for Oracle Database free edition. ### Free Edition Version Details -Oracle has released serveral versions of free edition, often **without chaning the RPM file name**. This toolkit can install _any_ free edition version. Which version is actually installed depends on the the actual RPM file in the software library, and possibly the command line switches. +Oracle has released serveral versions of free edition, often **without chaning the RPM file name**. The oracle-toolkit can install _any_ free edition version. Which version is actually installed depends on the the actual RPM file in the software library, and possibly the command line switches. Specific supported versions of Oracle Database 23 free edition currently includes: @@ -2568,7 +2575,7 @@ Run the database creation steps only: --config-db ``` -Run the full toolkit end-to-end: +Run the full oracle-toolkit end-to-end: ```bash ./install-oracle.sh \ @@ -2580,7 +2587,7 @@ Run the full toolkit end-to-end: --ora-pdb-name-prefix FREEPDB ``` -### Example Toolkit Execution for Free Edition +### Example Oracle Toolkit Execution for Free Edition In the following example, environment variables are used to specify the following values: @@ -2702,13 +2709,229 @@ ok: [db-23ai-free] ## Post installation tasks +### Validate the Oracle installation with ORAchk + +The orachk utility can be used to validate the Oracle installation. + +ORAchk will check for known problems with the Oracle installation and configuration, and provide recommendations for resolving any issues that are found. + +To run ORAchk, download the AHF utility from the Oracle support site. + +The following Oracle Support Note will provide the download link: + + `Autonomous Health Framework (AHF) - Including Trace File Analyzer and Orachk/Exachk (Doc ID 2550798.1)` + +ORAchk is a part of the AHF utility. It is not necessary to install the entire AHF utility to run ORAchk. + +The `check-oracle.sh` script provided with the oracle-toolkit will allow you to install, run and uninstall ORAchk on the target server. + +#### Options + +ORAchk can be installed on the target server using the following options: + +example 1: + +```text +./check-oracle.sh \ +--ahf-install \ +--db-name \ +--instance-ip-addr \ +--ahf-location +``` + +example 2: + +```text +./check-oracle.sh \ +--ahf-install \ +--inventory-file \ +--ahf-location +``` + +Running ORAchk on the target server is similar to the installation process, but the '--ahf-location' option is not required. + +example 1: + +```text +./check-oracle.sh \ +--run-orachk \ +--db-name \ +--instance-ip-addr +``` + +example 2: + +```text +./check-oracle.sh \ +--run-orachk \ +--db-name \ +--inventory-file +``` + +#### The AHF Zip file. + +The zip file must be uploaded to a GCS media bucket. + +The default 'directory' for this is AHF. + +For instance, the file `AHF-LINUX_v25.1.0.zip` would be uploaded to `gs://oracle-software/AHF/AHF-LINUX_v25.1.0.zip`. + +#### Install and Run ORAchk + +Use the the `check-oracle.sh` script to install and run ORAchk in one command. + +```bash +$ ./check-oracle.sh --help + Usage: check-oracle.sh + --instance-ip-addr + [ --extra-vars ] + [ --ahf-location ] + [ --db-name ] + [ --inventory-file ] + [ --ahf-install ] + [ --ahf-uninstall ] + [ --run-orachk ] + [ --help ] + [ --debug ] + +--ahf-install and --run-orachk may be combined to install and run +--extra-vars is used to pass any number of extra ansible vars + example: --extra-vars 'var1=val1 var2=val2' + +``` + +example output: +Note: skipped steps are omitted + +```text + +./check-oracle.sh --ahf-install \ + --instance-ip-addr 10.2.80.39 \ + --db-name ORCL \ + --ahf-location gs://oracle-software/AHF/AHF-LINUX_v25.1.0.zip + +PLAY [ORAchk: uninstall, install or run] *********************************************************************************************************************************************************************************************************************************** +... +PLAY [ORAchk: uninstall, install or run] *********************************************************************************************************************************************************************************************************************************** + +TASK [Check for AHF Installation] ****************************************************************************************************************************************************************************************************************************************** +ok: [ora-db-server-19c] +... +PLAY RECAP ***************************************************************************************************************************************************************************************************************************************************************** +ora-db-server-19c : ok=8 changed=2 unreachable=0 failed=0 skipped=24 rescued=0 ignored=0 + +``` + +#### Installing ORAchk + +Use the the `check-oracle.sh` script to install ORAchk. + +```bash + +./check-oracle.sh --ahf-install \ + --inventory-file inventory_files/inventory_ora-db-server-19c_ORCL \ + --ahf-location gs://oracle-software/AHF/AHF-LINUX_v25.1.0.zip + +``` +example output: +Note: skipped steps are omitted + +```text +PLAY [ORAchk: uninstall, install or run] ********************************************************************************************************************************************************************************************** + +TASK [Create AHF directory] *********************************************************************************************************************************************************************************************************** +ok: [ora-db-server-19c] + +... + +TASK [Run AHF setup] ****************************************************************************************************************************************************************************************************************** +changed: [ora-db-server-19c] + +PLAY RECAP **************************************************************************************************************************************************************************************************************************** +ora-db-server-19c : ok=7 changed=2 unreachable=0 failed=0 skipped=8 rescued=0 ignored=0 + +``` +#### Running ORAchk + +```bash +./check-oracle.sh --run-orachk \ + --db-name ORCL \ + --inventory-file inventory_files/inventory_ora-db-server-19c_ORCL +``` + +example output: +Note: skipped steps are omitted + +```text + +PLAY [ORAchk: uninstall, install or run] ********************************************************************************************************************************************************************************************** + +... + +TASK [Run ORAchk] ********************************************************************************************************************************************************************************************************************* +changed: [ora-db-server-19c] + +... + +TASK [Display local path of fetched file] ********************************************************************************************************************************************************************************************* +ok: [ora-db-server-19c] => { + "msg": "Fetched file is saved locally at: /tmp/orachk_ora-db-server-19c_ORCL_020525_193642.zip" +} + +PLAY RECAP **************************************************************************************************************************************************************************************************************************** +ora-db-server-19c : ok=6 changed=3 unreachable=0 failed=0 skipped=9 rescued=0 ignored=0 + +``` + +As shown in the message, the orachk zip file is saved locally at `/tmp/orachk_ora-db-server-19c_ORCL_020525_193642.zip`. + + +```text +$ unzip -l /tmp/orachk_ora-db-server-19c_ORCL_020525_193642.zip | head -12 +Archive: /tmp/orachk_ora-db-server-19c_ORCL_020525_193642.zip + Length Date Time Name +--------- ---------- ----- ---- + 0 02-05-2025 19:40 orachk_ora-db-server-19c_ORCL_020525_193642/ + 0 02-05-2025 19:40 orachk_ora-db-server-19c_ORCL_020525_193642/.standalone_html_gen/ + 0 02-05-2025 19:41 orachk_ora-db-server-19c_ORCL_020525_193642/log/ + 0 02-05-2025 19:40 orachk_ora-db-server-19c_ORCL_020525_193642/outfiles/ + 0 02-05-2025 19:40 orachk_ora-db-server-19c_ORCL_020525_193642/reports/ + 0 02-05-2025 19:40 orachk_ora-db-server-19c_ORCL_020525_193642/scripts/ + 0 02-05-2025 19:40 orachk_ora-db-server-19c_ORCL_020525_193642/upload/ + 650915 02-05-2025 19:40 orachk_ora-db-server-19c_ORCL_020525_193642/orachk_ora-db-server-19c_ORCL_020525_193642.html + 8959 02-05-2025 19:40 orachk_ora-db-server-19c_ORCL_020525_193642/localcmd.py.shell +``` + +Unzip the zip file, and open `orachk_ora-db-server-19c_ORCL_020525_193642/orachk_ora-db-server-19c_ORCL_020525_193642.html` in a browser + +#### Uninstalling ORAchk + +```bash +./check-oracle.sh --ahf-uninstall \ + --db-name ORCL \ + --oracle-server ora-db-server-19c +``` + +example output: +Note: skipped steps are omitted + +```text +PLAY [ORAchk: uninstall, install or run] ********************************************************************************************************************************************************************************************** + +TASK [Uninstall AHF] ****************************************************************************************************************************************************************************************************************** +changed: [ora-db-server-19c] + +PLAY RECAP **************************************************************************************************************************************************************************************************************************** +ora-db-server-19c : ok=1 changed=1 unreachable=0 failed=0 skipped=14 rescued=0 ignored=0 +``` + ### Reset passwords The toolkit does not use or store any passwords. At runtime, passwords for the Oracle SYS and SYSTEM database users are set with strong, unique, and randomized passwords that are not written to or persisted in any OS files. -Change the passwords immediately after running the toolkit. +Change the passwords immediately after running the oracle-toolkit. To change the passwords, connect to the database by using a SYSDBA administrative connection and change the passwords by using the SQL Plus @@ -2723,7 +2946,7 @@ SQL> password SYSTEM ### Validate the environment After deployment, you can validate your environment using several scripts that -are provided with the toolkit. +are provided with the oracle-toolkit. #### Listing Oracle ASM devices @@ -2818,7 +3041,7 @@ User: oracle You can apply Oracle Release Update (RU) or Patch Set Update (PSU) patches to both the Grid Infrastructure and Database homes by using the -`apply-patch.sh` script of the toolkit. +`apply-patch.sh` script of the oracle-toolkit. By default, `install-oracle.sh` updates to the latest available patch. To apply a specific patch instead, use the `--no-patch` option in `install-oracle.sh` @@ -2908,7 +3131,7 @@ By default, if RAC GI and RDBMS homes are of the same base release, the You can skip all RU/PSU patching steps and install only the base software by specifying the command line option `--no-patch`. You can then apply patches -separately later, either manually or by using the toolkit. +separately later, either manually or by using the oracle-toolkit. Alternatively, you can apply RAC GI and RDBMS patches independently from the base software installations by using the script `apply-patch.sh`. This script @@ -2918,11 +3141,11 @@ The list of RU/PSU patches to apply are defined by the `gi_patches` and `rdbms_patches` variables. By default, both are specified in the `roles/common/defaults/main.yml` Ansible file. For each major Oracle release, you can specify multiple versions from the various quarterly releases When you -install by using `install-oracle.sh`, the toolkit uses the most recent patch +install by using `install-oracle.sh`, the oracle-toolkit uses the most recent patch version. When creating a database, if the RDBMS home software is no longer at the base -release because it was patched during installation, the toolkit uses the Oracle +release because it was patched during installation, the oracle-toolkit uses the Oracle `datapatch` utility to apply patches at the database level, which is known as _SQL level patching_. @@ -2954,7 +3177,7 @@ If you do not specify a value on the `--compatible-rdbms` parameter, the RDBMS compatibility of the ASM disk group is set to the major version level that is defined on the `--ora-version` parameter. -To patch RAC databases, the toolkit performs the following actions: +To patch RAC databases, the oracle-toolkit performs the following actions: 1. Stops the RAC databases in their homes by using the "stop home" option from the master node. diff --git a/roles/check-oracle/files/login.sql b/roles/check-oracle/files/login.sql new file mode 100644 index 00000000..11b6532c --- /dev/null +++ b/roles/check-oracle/files/login.sql @@ -0,0 +1,20 @@ +/* +# Copyright 2025 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +*/ + +SET HEADING ON ECHO OFF TERMOUT ON TAB OFF TRIMOUT ON TRIMS ON NEWPAGE 1 PAGES 32767 LINES 500 +SET LONG 20000000 LONGCHUNKSIZE 50000 FEEDBACK OFF VERIFY OFF TIMING OFF SQLPROMPT \"SQL> \" COLSEP '|' +ALTER SESSION SET CURSOR_SHARING=EXACT; + diff --git a/roles/check-oracle/files/orachk-quicktest.sh b/roles/check-oracle/files/orachk-quicktest.sh new file mode 100644 index 00000000..38b562d0 --- /dev/null +++ b/roles/check-oracle/files/orachk-quicktest.sh @@ -0,0 +1,22 @@ +#!/bin/bash + +: << 'EXPEDITED_TESTING' + +When developing playbooks and scripts, it may not be important to run orachk. + +What is needed during development is to have a facsimile that provides the outputs +needed for testing, but takes seconds rather than minutes + +Enable this with by adding this parameter to check-oracle.sh: ' --extra-vars "expedited_testing=true" ' + +EXPEDITED_TESTING + + +timestamp=$(date +%Y-%m-%d_%H-%m-%S) + +# not really a zip file +testRptFile="/tmp/orachk-quick-test_${timestamp}.zip" + +echo "this is a dummy orachk report" > $testRptFile + +echo "UPLOAD this file if necessary $testRptFile" diff --git a/roles/check-oracle/meta/main.yml b/roles/check-oracle/meta/main.yml new file mode 100644 index 00000000..d15a849b --- /dev/null +++ b/roles/check-oracle/meta/main.yml @@ -0,0 +1,17 @@ +# Copyright 2020 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +--- +dependencies: + - role: common diff --git a/roles/check-oracle/vars/main.yml b/roles/check-oracle/vars/main.yml new file mode 100644 index 00000000..f746bbfc --- /dev/null +++ b/roles/check-oracle/vars/main.yml @@ -0,0 +1,33 @@ +# Copyright 2025 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +--- +oratab_path: "/etc/oratab" +ahf_extract_path: "/u01/AHF" +orachk_script_dir: "/u01/orachk" +extended_path: "/usr/local/bin:{{ ansible_env.PATH | default('/usr/bin:/usr/sbin') }}" +# Default is to NOT uninstall AHF +uninstall_ahf: false +# default is to NOT run orachk +run_orachk: false +expedited_testing: false + +ORAENV_ASK: "NO" +RAT_TIMEOUT: "240" +ORACHK_BASE: "/opt/oracle.ahf" +AHFCTL_PATH: "{{ ORACHK_BASE }}/bin/ahfctl" +SQLPATH: "{{ ORACHK_BASE }}" +ORACLE_PATH: "{{ ORACHK_BASE }}" +ORACLE_OWNER: "oracle" +ORACLE_GROUP: "oinstall" +RAT_OUTPUT: "{{ ORACHK_BASE }}/{{ check_name }}"