Update README.md for Post-Deployment (#19)

* Update README.md Signed-off-by: Shelley Chase <[email protected]> * Modify the status CLI script to halt any further processing if no applications were returned (indicates a configuration issue or non-running instance). Improved documentation on post-deployment tailoring which should be done prior to usage. * Correcting bad PROPATH entry * Correcting logic for session metrics * Correcting line endings for shell script * Refactoring bin scripts, adjusting comments in configs * Minor change to default logfile name * Set execute bit on .sh on deployment * Always use the ABL logger framework for command logging --------- Signed-off-by: Shelley Chase <[email protected]> Co-authored-by: DustinGrau-PSC <[email protected]>
progress · May 18, 2023 · dbb227c · dbb227c
1 parent 51e5403
commit dbb227c
Show file tree

Hide file tree

Showing 14 changed files with 147 additions and 51 deletions.
diff --git a/PAS/Management/OEManager/ABL/README.md b/PAS/Management/OEManager/ABL/README.md
@@ -17,14 +17,30 @@ The deployment method has changed since previous versions with use of a new **ut
 
 **Automated Deployment**
 
-Run the command `proant deploy -Dpath=[PATH_TO_INSTANCE]` to expand/unzip the **utils.zip** into your PAS instance's **CATALINA_BASE/utils/** folder. A new folder will be created if necessary, and any existing files will be overwritten if deploying on top of a prior deployment. This will overwrite any customization to an `oemanager.properties` file.
+Run the command `proant deploy -Dpath=[PATH_TO_INSTANCE]` to expand/unzip the **utils.zip** into your PAS instance's **CATALINA_BASE/utils/** folder. A new folder will be created if necessary, and any existing files will be overwritten if deploying on top of a prior deployment. This will overwrite any customization to an `oemanager.properties` file (when present).
 
 **Manual Deployment**
 
-Unzip the **utils.zip** file into a new "utils" folder on the target OS image (physical or virtual machine, or container). This may be placed in either a PAS instance you have direct access to (via the OS filesystem) or a central location if desiring to manage multiple remote PAS instances.
+Unzip the **utils.zip** file into a new "utils" folder anywhere on the target OS image (physical or virtual machine, or container). This may be placed in either a PAS instance you have direct access to (via the OS filesystem) or an arbitrary location if desiring to manage multiple remote PAS instances from a standalone instance of the utilities.
+
+## Post-Deployment ##
+
+Once the **utils.zip** has been deployed there will be minor tailoring required. How the utilities were deployed and whether you are managing a local or remote PAS instance will affect which properties must be modified. But first, the following should be kept in mind regardless of these factors:
+
+- The `userid` and `passwd` for the OEManager webapp must always be specified in one of these two ways:
+	1. Supply the properties on the command line via `-Duserid=<username>` and `-Dpasswd=<password>`.
+	1. Or, modify the `oemanager.properties` file in the deployed location to use default values.
+- The `ablapp` (and `webapp` when necessary) should be checked and modified appropriately through either command line parameters (`-Dablapp` and `-Dwebapp`) or set with defaults in the `oemanager.properties` file as it is not possible to assume which app names are intended for tasks.
+
+**Deployed to a PAS Instance**
 
 - If placed within a PAS instance in a "utils" folder the tools will automatically tailor themselves to use properties from the PAS instance, such as the HTTP or HTTPS port.
-- If **not** placed directly within a PAS instance then you must either pass command-line parameters or edit the `oemanager.properties` file to supply the necessary defaults for either or both of the following groups of properties:
+- The `port` property may still be overridden by use of the `-Dscheme` command line parameters to prefer either "http" or "https" while passing a parameter of `-Dport` will be the default used if either an HTTP or HTTPS port cannot be inferred from the local PAS instance.
+- Note: When deployed into a PAS instance as a "utils" folder, the properties `-Dpas.root` and `-Dinstance` should be automatically inferred from the directory structure.
+
+**Deployed Externally Usage**
+
+- If **not** placed directly within a PAS instance then you must either pass command-line parameters or edit the `oemanager.properties` file to supply the necessary defaults for the following properties:
 	- To control remote PAS instances: set the `scheme`, `hostname`, and `port` properties for the intended instance.
 		- eg. "-Dscheme=http -Dhostname=localhost -Dport=8810"
 	- To control local PAS instances: the `pas.root` and `instance` properties (these will form the CATALINA_BASE path).

diff --git a/PAS/Management/OEManager/ABL/USAGE.md b/PAS/Management/OEManager/ABL/USAGE.md
@@ -1,12 +1,12 @@
 # OEManager CLI Tools - Usage Guide #
 
-Execute the `oemanager[.bat]` command from within the utils folder to run the desired tasks from the command line. Where possible, default values will be determined automatically for HTTP/S ports, server paths, the instance's name, and the default ABL Application name. Any required or optional parameters may be overridden via the command line or by editing the `oemanager.properties` file in advance.
+Execute the `oemanager.[bat|sh]` command from within the utils folder to run the desired tasks from the command line. Where possible, default values will be determined automatically for HTTP/S ports, server paths, the instance's name, and the default ABL Application name. Any required or optional parameters may be overridden via the command line or by editing the `oemanager.properties` file in advance.
 
 Note that each request to an OEM-API endpoint will be automatically logged to a `commands.log` file. No sensitive data will be included in these logged messages, only PID's and operationally-relevant information will be included in the URL or as query parameters to the API endpoint.
 
 ## Basic Usage ##
 
-The following represents the default usage for all tasks which can be executed using the CLI tools and is the standard output when the `oemanager[.bat]` command is run without a task name.
+The following represents the default usage for all tasks which can be executed using the CLI tools and is the standard output when the `oemanager.[bat|sh]` command is run without a task name.
 
      [echo] Usage Instructions:
      [echo]

diff --git a/PAS/Management/OEManager/ABL/bin/oemanager.bat b/PAS/Management/OEManager/ABL/bin/oemanager.bat
@@ -28,18 +28,14 @@ if exist "%ANTSCRIPT%" goto START
    goto END
 
 :START
-REM Remember the original ANT_HOME
-set _ANT_HOME=%ANT_HOME%
-set ANT_HOME="%DLC%"\ant
-
 REM Set JAVA_HOME by calling java_env
 if exist "%DLC%\bin\java_env.bat" (
     call "%DLC%\bin\java_env.bat"
 )
 
-REM Use the oemanager.xml as task instructions to Ant, passing all other parameters
-call "%ANTSCRIPT%" -f oemanager.xml %*
-set ANT_HOME=%_ANT_HOME%
+REM Use the PowerShell utility to execute the Ant utility with all given parameters
+PowerShell.exe -executionpolicy bypass -File "oemanager.ps1" %*
+
 goto END
 
 :END
diff --git a/PAS/Management/OEManager/ABL/bin/oemanager.ps1 b/PAS/Management/OEManager/ABL/bin/oemanager.ps1
@@ -0,0 +1,41 @@
+<#
+.NOTES
+===========================================================================
+Created on:       05/16/2023
+Updated on:       05/16/2023
+Created by:       dugrau
+Organization:     Progress Software Corp. | OpenEdge
+Filename:         oemanager.ps1
+===========================================================================
+.DESCRIPTION
+This Powershell script is a called by the oemanager.bat script to execute
+the Ant utility in the DLC installation directory (DLC/ant). It utilizes
+the oemanager.xml file to configure all tasks and parameters available.
+
+This provides a command line interface to the OEManager webapp installed
+to a PAS instance to manage and monitor that instance.
+#>
+
+#---- Local Variables ----#
+[string]$script:_dlcPath=(Get-ChildItem -Path Env:DLC).Value
+[string]$script:_antPath="$script:_dlcPath\ant\bin\ant.bat"
+[string]$script:_taskFilePath="$PSScriptRoot\oemanager.xml"
+[string]$script:_taskArgs=""
+
+# Prefix arguments with a "-D" as necessary. This allows the user to pass parameters
+# without the prefix (if they forgot) and allows the task name to be anywhere within
+# the list of arguments passed to this script. Note that multiple tasks may be run,
+# in the order by which they are given.
+
+foreach ($arg in $args) {
+    if ($arg.Contains("=") -and $arg -notlike "-D*") {
+        $thisArg = " -D$arg"
+    }
+    else {
+        $thisArg = " $arg"
+    }
+    $script:_taskArgs += $thisArg
+}
+
+# Run the ant utility from DLC/ant as previously discovered
+Invoke-Expression "& $script:_antPath -f $script:_taskFilePath $script:_taskArgs"
diff --git a/PAS/Management/OEManager/ABL/bin/oemanager → ...Management/OEManager/ABL/bin/oemanager.sh b/PAS/Management/OEManager/ABL/bin/oemanager → ...Management/OEManager/ABL/bin/oemanager.sh
@@ -1,5 +1,6 @@
 #!/bin/sh
 # OpenEdge - OEManager CLI Utility
+
 PROG=`basename $0`
 
 # Utility must be run with DLC environment variable set
@@ -48,6 +49,20 @@ then
     exit 1
 fi
 
-# use the oemanager.xml as task instructions to Ant, passing all other parameters
+# Ensure arguments (with exception of the task name) are prefixed with -D for Ant
+taskArgs=()
+
+for arg in "$@"; do
+  if [[ "$arg" == *"="* ]] && [[ "$arg" != "-D"* ]]; then
+    taskArg="-D$arg"
+  else
+    taskArg="$arg"
+  fi
+
+  taskArgs+=("$taskArg")
+done
+
+# Uses the oemanager.xml as task instructions to Ant, passing all task arguments
 ANT_HOME=$DLC/ant ; export ANT_HOME
-exec $ANTSCRIPT -f oemanager.xml $@
+exec $ANTSCRIPT -f oemanager.xml $taskArgs
+
diff --git a/PAS/Management/OEManager/ABL/build.xml b/PAS/Management/OEManager/ABL/build.xml
@@ -256,6 +256,9 @@
         <!-- Unzip the contents to a like-named folder in the target instance. -->
         <mkdir dir="${path}/utils"/>
         <unzip src="${basedir}/utils.zip" dest="${path}/utils" overwrite="true"/>
+
+		<!-- Set execution privilege on shell scripts. -->
+		<chmod dir="${path}/utils" perm="ug+x" includes="*.sh"/>
     </target>
 
     <target name="deploy_manager">

diff --git a/PAS/Management/OEManager/ABL/conf/oemanager.properties b/PAS/Management/OEManager/ABL/conf/oemanager.properties
@@ -1,4 +1,4 @@
-# build.properties file - Modify as Needed
+# oemanager.properties file - Modify as Needed for PAS Instance
 #
 # Changing the scheme will affect the port
 # used when run from within a PAS instance

diff --git a/PAS/Management/OEManager/ABL/conf/oemanager.xml b/PAS/Management/OEManager/ABL/conf/oemanager.xml
@@ -1,8 +1,8 @@
 <project name="OEManager CLI Tools" basedir="." default="usage">
 
-    <!--
-        Copyright 2020-2023 Progress Software Corporation
+    <!-- Copyright 2020-2023 Progress Software Corporation -->
 
+    <!--
         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
@@ -22,7 +22,7 @@
     <property file="${basedir}/oemanager.properties"/>
 
     <target name="usage" description="Usage Instructions">
-        <init_oe/> <!-- Set standard environment variables. -->
+    	<init_oe/> <!-- Initialize all OpenEdge properties. -->
 
         <echo message="${line.separator}"/>
         <echo message="CLI utilities for monitoring and management of a PASOE instance."/>
@@ -92,15 +92,16 @@
         <echo message="                                          When no session ID provided, all available Client HTTP Sessions will be expired"/>
         <echo message="                        [OPTIONAL] -Dterminateopt=${terminateopt} - Termination Option: 0=graceful, 1=forced, 2=finish+stop"/>
         <echo message="${line.separator}"/>
-        <echo message="${line.separator}Available common parameters with their defaults, override as necessary:"/>
+        <echo message="${line.separator}Current parameter values, override as necessary:"/>
         <echo message="    -Dscheme=${scheme}"/>
         <echo message="      -Dhost=${host}"/>
         <echo message="      -Dport=${port}"/>
         <echo message="    -Duserid=${userid}"/>
         <echo message="    -Dpasswd=${passwd}"/>
         <echo message="  -Dpas.root=${pas.root} - PAS parent directory, above the instance"/>
         <echo message="  -Dinstance=${instance} - Physical instance name (folder, not alias)"/>
-        <echo message="    -Dablapp=${ablapp} - ABL Application name for all tasks above"/>
+        <echo message="    -Dablapp=${ablapp}"/>
+    	<echo message="    -Dwebapp=${webapp}"/>
         <echo message="${line.separator}NOTE: The name of the ABLApp is case-sensitive!"/>
         <echo message="${line.separator}"/>
         <echo message="CATALINA_HOME: ${catalina.home}"/>
@@ -591,7 +592,7 @@
             <propath>
                 <pathelement path="${basedir}"/>
                 <pathelement path="${dlcHome}/tty/netlib/OpenEdge.Net.pl"/>
-                <pathelement path="${dlcHome}/tty/netlib/OpenEdge.ServerAdmin.pl"/>
+                <pathelement path="${dlcHome}/tty/OpenEdge.ServerAdmin.pl"/>
             </propath>
             <Parameter name="Scheme" value="${scheme}"/>
             <Parameter name="Host" value="${host}"/>
@@ -624,7 +625,7 @@
             <propath>
                 <pathelement path="${basedir}"/>
                 <pathelement path="${dlcHome}/tty/netlib/OpenEdge.Net.pl"/>
-                <pathelement path="${dlcHome}/tty/netlib/OpenEdge.ServerAdmin.pl"/>
+                <pathelement path="${dlcHome}/tty/OpenEdge.ServerAdmin.pl"/>
             </propath>
             <Parameter name="Scheme" value="${scheme}"/>
             <Parameter name="Host" value="${host}"/>
@@ -656,7 +657,7 @@
             <propath>
                 <pathelement path="${basedir}"/>
                 <pathelement path="${dlcHome}/tty/netlib/OpenEdge.Net.pl"/>
-                <pathelement path="${dlcHome}/tty/netlib/OpenEdge.ServerAdmin.pl"/>
+                <pathelement path="${dlcHome}/tty/OpenEdge.ServerAdmin.pl"/>
             </propath>
             <Parameter name="Scheme" value="${scheme}"/>
             <Parameter name="Host" value="${host}"/>
@@ -688,7 +689,7 @@
             <propath>
                 <pathelement path="${basedir}"/>
                 <pathelement path="${dlcHome}/tty/netlib/OpenEdge.Net.pl"/>
-                <pathelement path="${dlcHome}/tty/netlib/OpenEdge.ServerAdmin.pl"/>
+                <pathelement path="${dlcHome}/tty/OpenEdge.ServerAdmin.pl"/>
             </propath>
             <Parameter name="Scheme" value="${scheme}"/>
             <Parameter name="Host" value="${host}"/>
@@ -723,7 +724,7 @@
             <propath>
                 <pathelement path="${basedir}"/>
                 <pathelement path="${dlcHome}/tty/netlib/OpenEdge.Net.pl"/>
-                <pathelement path="${dlcHome}/tty/netlib/OpenEdge.ServerAdmin.pl"/>
+                <pathelement path="${dlcHome}/tty/OpenEdge.ServerAdmin.pl"/>
             </propath>
             <Parameter name="Scheme" value="${scheme}"/>
             <Parameter name="Host" value="${host}"/>
@@ -757,7 +758,7 @@
             <propath>
                 <pathelement path="${basedir}"/>
                 <pathelement path="${dlcHome}/tty/netlib/OpenEdge.Net.pl"/>
-                <pathelement path="${dlcHome}/tty/netlib/OpenEdge.ServerAdmin.pl"/>
+                <pathelement path="${dlcHome}/tty/OpenEdge.ServerAdmin.pl"/>
             </propath>
             <Parameter name="Scheme" value="${scheme}"/>
             <Parameter name="Host" value="${host}"/>
@@ -792,7 +793,7 @@
             <propath>
                 <pathelement path="${basedir}"/>
                 <pathelement path="${dlcHome}/tty/netlib/OpenEdge.Net.pl"/>
-                <pathelement path="${dlcHome}/tty/netlib/OpenEdge.ServerAdmin.pl"/>
+                <pathelement path="${dlcHome}/tty/OpenEdge.ServerAdmin.pl"/>
             </propath>
             <Parameter name="Scheme" value="${scheme}"/>
             <Parameter name="Host" value="${host}"/>
@@ -828,7 +829,7 @@
             <propath>
                 <pathelement path="${basedir}"/>
                 <pathelement path="${dlcHome}/tty/netlib/OpenEdge.Net.pl"/>
-                <pathelement path="${dlcHome}/tty/netlib/OpenEdge.ServerAdmin.pl"/>
+                <pathelement path="${dlcHome}/tty/OpenEdge.ServerAdmin.pl"/>
             </propath>
             <Parameter name="Scheme" value="${scheme}"/>
             <Parameter name="Host" value="${host}"/>
@@ -862,7 +863,7 @@
             <propath>
                 <pathelement path="${basedir}"/>
                 <pathelement path="${dlcHome}/tty/netlib/OpenEdge.Net.pl"/>
-                <pathelement path="${dlcHome}/tty/netlib/OpenEdge.ServerAdmin.pl"/>
+                <pathelement path="${dlcHome}/tty/OpenEdge.ServerAdmin.pl"/>
             </propath>
             <Parameter name="Scheme" value="${scheme}"/>
             <Parameter name="Host" value="${host}"/>
@@ -895,7 +896,7 @@
             <propath>
                 <pathelement path="${basedir}"/>
                 <pathelement path="${dlcHome}/tty/netlib/OpenEdge.Net.pl"/>
-                <pathelement path="${dlcHome}/tty/netlib/OpenEdge.ServerAdmin.pl"/>
+                <pathelement path="${dlcHome}/tty/OpenEdge.ServerAdmin.pl"/>
             </propath>
             <Parameter name="Scheme" value="${scheme}"/>
             <Parameter name="Host" value="${host}"/>
@@ -927,7 +928,7 @@
             <propath>
                 <pathelement path="${basedir}"/>
                 <pathelement path="${dlcHome}/tty/netlib/OpenEdge.Net.pl"/>
-                <pathelement path="${dlcHome}/tty/netlib/OpenEdge.ServerAdmin.pl"/>
+                <pathelement path="${dlcHome}/tty/OpenEdge.ServerAdmin.pl"/>
             </propath>
             <Parameter name="Scheme" value="${scheme}"/>
             <Parameter name="Host" value="${host}"/>
@@ -959,7 +960,7 @@
             <propath>
                 <pathelement path="${basedir}"/>
                 <pathelement path="${dlcHome}/tty/netlib/OpenEdge.Net.pl"/>
-                <pathelement path="${dlcHome}/tty/netlib/OpenEdge.ServerAdmin.pl"/>
+                <pathelement path="${dlcHome}/tty/OpenEdge.ServerAdmin.pl"/>
             </propath>
             <Parameter name="Scheme" value="${scheme}"/>
             <Parameter name="Host" value="${host}"/>
@@ -1011,7 +1012,7 @@
             <propath>
                 <pathelement path="${basedir}"/>
                 <pathelement path="${dlcHome}/tty/netlib/OpenEdge.Net.pl"/>
-                <pathelement path="${dlcHome}/tty/netlib/OpenEdge.ServerAdmin.pl"/>
+                <pathelement path="${dlcHome}/tty/OpenEdge.ServerAdmin.pl"/>
             </propath>
             <!-- End Database Connections -->
             <Parameter name="Scheme" value="${scheme}"/>

diff --git a/PAS/Management/OEManager/ABL/release.txt b/PAS/Management/OEManager/ABL/release.txt
@@ -1 +1 @@
-2023-03-10T15:01:53.454
+2023-05-18T07:26:44.981
diff --git a/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getLocks.p b/PAS/Management/OEManager/ABL/src/OpenEdge/ApplicationServer/Cli/getLocks.p
@@ -106,7 +106,7 @@ assign
     .
 
 oAblApps:AutoExpand = true.
-oAgentList:AutoExpand = true. 
+oAgentList:AutoExpand = true.
 
 function HasAgent returns logical ( input poInt as integer ) forward.