Management Gateway Administration Tasks
Some administration tasks may be required after installing a Management Gateway.
Update Management Gateway Properties
Management Gateway Port
GatewayPort
property from the
gateway.properties
file.
- On Linux platforms, the
gateway.properties
file is located under:/opt/oracle/mgmt_agent/plugins/GatewayProxy/stateDir/config
. - On Windows platforms, the
gateway.properties
file is located under:C:\Oracle\mgmt_agent\plugins\GatewayProxy\stateDir\config
.
To change the Management Gateway port value, edit the
gateway.properties
file and replace the current value of the
GatewayPort
property with the desired port number.
gateway.properties
file, the
Management Gateway service must be restarted.
-
For Oracle Linux 6, use:
/sbin/initctl restart mgmt_gateway
-
For Oracle Linux 7, use:
systemctl restart mgmt_gateway
-
For Windows, use:
net stop mgmt_gateway net start mgmt_gateway
If the GatewayPort
property value changes then any
Management Agents using that Management Gateway must be changed to use the new port
value. For details, see Update Management Agents after Changes to Management Gateway Configuration
Management Gateway Credentials
The Gateway is typically configured to use credentials: username and password are required to connect to it.
Such credentials are stored in Oracle Wallets. For information about how to add, update or delete credentials, see Configure Management Gateway Credentials.
If the Management Gateway credentials change, then any Management Agents using the Management Gateway must be changed to use the new credentials. For information, see Update Management Agents after Changes to Management Gateway Configuration.
Configure Management Gateway Credentials
This section describes how to manage credentials which may be needed for Management Gateway.
The Management Gateway stores sensitive information, such as credentials, in Oracle Wallets.
After installing a Management Gateway, you may need to configure credentials.
If changes have been made using the CLI commands, the gateway must be restarted. For information about CLI commands, see Oracle Cloud Infrastructure CLI Command Reference.
Add or Update Credentials
To add credentials or update existing ones, use the gateway_credentials
script with the upsertCredentials
operation.
- Linux: The
gateway_credentials.sh
script is located in the/opt/oracle/mgmt_agent/plugins/GatewayProxy/stateDir/bin
directory. - Windows: The
gateway_credentials.bat
script is located in theC:\Oracle\mgmt_agent\plugins\GatewayProxy\stateDir\bin
directory.
-
Create a text file with the username and password for the gateway:
GatewayUsername=<USER_NAME> GatewayPassword=<USER_PASSWORD>
For example:GatewayUsername=oracle2 GatewayPassword=welcomepwd
For example, you can save the text file as cred.properties.
-
Add credentials using a text file.
-
For Linux, use:
gateway_credentials.sh -o upsertCredentials
For example, you can run the following on Linux using the
cred.properties
file:cat cred.properties | sudo -u mgmt_agent sh /opt/oracle/mgmt_agent/plugins/GatewayProxy/stateDir/bin/gateway_credentials.sh -o upsertCredentials
-
For Windows, use:
gateway_credentials.bat -o upsertCredentials
For example, you can run the following on Windows using thecred.properties
file::type cred.properties | C:\Oracle\mgmt_agent\plugins\GatewayProxy\stateDir\bin\gateway_credentials.bat -o upsertCredentials
-
-
Delete the text file created in step 1.
The text file contains sensitive information. Customers are responsible for deleting the credentials text file after completing the add or update credentials operation.
Delete Credentials
To delete credentials, use the gateway_credentials
script with the deleteCredentials
operation.
- Linux:
The
gateway_credentials.sh
script is located in the/opt/oracle/mgmt_agent/plugins/GatewayProxy/stateDir/bin
directory.Syntax:gateway_credentials.sh -o deleteCredentials
Example:sudo -u mgmt_agent sh /opt/oracle/mgmt_agent/plugins/GatewayProxy/stateDir/bin/gateway_credentials.sh -o deleteCredentials
- Windows:
The
gateway_credentials.bat
script is located in theC:\Oracle\mgmt_agent\plugins\GatewayProxy\stateDir\bin
directory.Syntax:gateway_credentials.bat -o deleteCredentials
Example:C:\Oracle\mgmt_agent\plugins\GatewayProxy\stateDir\config\bin\gateway_credentials.bat -o deleteCredentials
Deleting credentials does not delete the wallet that contained the credentials.
Update Management Agents after Changes to Management Gateway Configuration
If the Management Gateway configuration changes, the Management Agent may also have to be changed.
-
Gateway host: If the Gateway is moved to another host, or if the Gateway host is renamed, then any Agents using the Gateway must be changed to use the new hostname.
In this case, the Management Agent parameter
GatewayServerHost
must be updated to use the new Gateway. -
Gateway port: If the Gateway port value changes, then any Agents using the Gateway must be changed to use the new port value.
In this case, the Management Agent parameter
GatewayServerPort
must be updated to use the new Gateway port. -
Gateway credentials: If the credentials required to connect to the Management Gateway (such as username and password) are changed, then any Agents using the Gateway must be changed to use the new credentials. For information, see Credential Type for Management Gateways and Proxies and Add or Update Credentials.
Update Proxy Credentials for Management Gateway
You can update existing external proxy credentials for the Management Gateway.
Prerequisites:
ProxyHost
ProxyPort
ProxyHost=myproxy.example.com
ProxyPort=80
Step 1: Create request body for updating the proxy credentials
Provide the new username and password in credentials file using the following properties:
ProxyUser
: User name for authentication with the proxy.ProxyPassword
: Password of the user for the authentication with the proxy.
The above credentials properties are case-sensitive.
See below sample-proxycreds.json
sample credentials
file:
{"source":"agent.%%agentId%%",
"name":"ManagementAgent-Proxy",
"type":"ProxyCreds",
"description":"Proxy Credentials",
"properties":[
{"name":"ProxyUser","value":"<UserName>"},
{"name":"ProxyPassword","value":"<Password>"}]}
Step 2: Execute command to update the proxy credentials
- For Linux:
cat sample-proxycreds.json | sudo -u mgmt_agent /opt/oracle/mgmt_agent/agent_inst/bin/credential_mgmt.sh -o upsertCredentials -s Agent
- For Windows:
type sample-proxycreds.json | C:\oracle\mgmt_agent\agent_inst\bin\credential_mgmt.bat -o upsertCredentials -s Agent
Step 3 : Restart Management Gateway
- For Linux:
sudo systemctl restart mgmt_gateway
- For Windows:
net stop mgmt_gateway net start mgmt_gateway
The credentials are used by the Management Gateway to communicate with Oracle Cloud Infrastructure services. Changing its format or removing the credentials can have an adverse effect on the Management Gateway's ability to communicate back to Oracle Cloud Infrastructure services.
Enable Batching for Management Gateway
After installing Management Gateway, you can enable batching to provide better and quicker management of the logging uploads to the Logging Analytics service.
gateway.properties
file:BatchingEnabled=true
After updating the gateway.properties
file, the Management Gateway service must be restarted. To restart it, run the following:
- For Oracle Linux 6, use:
/sbin/initctl restart mgmt_gateway
- For Oracle Linux 7, use:
systemctl restart mgmt_gateway
Upgrade Management Gateway
Upgrade Management Gateway on Linux
- Download the latest version of the
RPM
file containing the software download file. For details, see Download Management Gateway Software. - To upgrade the gateway, run the rpm command
with the upgrade option:
rpm -U
.sudo rpm -U <rpm_file_name.rpm>
Upgrade Management Gateway on Linux using a Zip file
To upgrade an gateway on Linux using a Zip file, do the following:
- Download the latest version of the ZIP file containing the gateway software download file, For details, see Download Management Gateway Software
- Navigate to the directory where you have downloaded the management gateway software ZIP file and unzip it to any preferred location.
- To upgrade the gateway, run the
installer.sh
script with the option:-u
installer.sh -u
- The output looks similar to the
following:
sudo ./installer.sh -u Checking pre-requisites Checking available disk space for gateway upgrade Checking agent version Executing install Unpacking software zip Copying files to destination dir (/opt/oracle/mgmt_agent) Updating communication wallet Creating 'mgmt_gateway' daemon Starting mgmt_gateway Gateway Install Logs: /opt/oracle/mgmt_agent/installer-logs/installer.log Gateway upgrade successful
Upgrade Management Gateway on Windows
- Log in as an Administrator user and open a command prompt window.
- Download the latest version of the
ZIP
file containing the agent software download file. For details, see Download the Management Gateway Software. - Navigate to the directory where you have downloaded the management agent software
ZIP
file and unzip it to any preferred location. - To upgrade the gateway, run the
installer.bat
script with the-u
option:installer.bat -u
For example:
The output looks similar to the following:C:\Users\test_agent>installer.bat -u
JAVA_HOME found at: C:\Program Files\Java\jdk1.8.0_321 Executing upgrade Unpacking software zip Copying files to destination dir (C:\Oracle\mgmt_agent) Updating communication wallet Creating mgmt_gateway service Management Gateway upgrade successful The Oracle Management Gateway service is starting.... The Oracle Management Gateway service was started successfully.
Remove Management Gateway
When removing a Management Gateway from a host, the Management Gateway is unregistered from the Management Agents Cloud Service before it’s removed from the host.
To remove or uninstall Management Gateway from the following operating systems, you can follow these steps:
Remove Management Gateway on Linux using the RPM command
rpm
command with the -e
option:sudo rpm -e <rpm_name>
Remove Management Gateway on Linux using an uninstaller script
Execute the uninstaller.sh
script if you installed the
Management Gateway using the ZIP
files.
The output looks similar to the following:
$ sudo bash /opt/oracle/mgmt_agent/agent_inst/bin/uninstaller.sh
Executing pre-remove step from uninstall
Attempting to remove the Gateway from Management Agent Cloud service, please do not interrupt...
Attempting to remove the Gateway from Management Agent Cloud service,please do not interrupt...
Gateway was removed from Management Agent Cloud service successfully.
Detected Oracle Linux Server (Red Hat family):
Stopping mgmt_gateway...
Removing mgmt_gateway daemon from systemd...
Removed symlink /etc/systemd/system/multi-user.target.wants/mgmt_gateway.service.
Gateway was removed from the host successfully.
Executing post-remove step from uninstall
Gateway state directory was removed from the host successfully.
If you installed the Management Gateway using an external volume on Linux, the Management Gateway uninstaller script removes all the data under the
/opt/oracle/mgmt_agent
directory, and on some operating
systems, also removes the target directory the symlink points to.
Remove Management Gateway on Windows
Open a Command Prompt window, navigate to the Management Gateway install
base directory and execute the uninstaller.bat
script.
C:\Oracle>mgmt_agent\uninstaller.bat
Removing Management Gateway from the OCI service console.
Attempting to remove the agent from Management Agent Cloud service, do not interrupt...
Gateway was removed from the Management Agent Cloud service successfully.
Removing Management Gateway service from the host
Management Gateway service was removed from the host successfully
Removing Management Gateway directories
Ensure that all other command prompt windows are closed or that they are
not pointing to the Management Gateway home directory before running the
uninstaller.bat
script.
Use a Non-default OS User to Install Management Gateway
Oracle recommends to perform the Management Gateway installation using the
default OS user: mgmt_agent
, but depending on your requirements, you may
need to perform the installation using a different OS user.
This section describes how to install the Management Gateway using a different user
from mgmt_agent
, the default OS user.
Prerequisites
When choosing an OS user other than mgmt_agent
to perform the
Management Gateway installation on Linux or Unix systems, the following
considerations need to be taken:
- Select an OS user with limited privileges.
The default mgmt_agent OS user is a least privilege OS user with no login shell. If you decide to select another OS user instead, ensure the chosen user has limited privileges.
- Management Gateway is a multi-threaded application and each thread (LWP) counts
towards the OS user limit. Ensure that the user limit
(
ulimit
) formax user processes
is set accordingly by checking:ulimit -u
Choosing an inadequate limit can result in instability of the Management Gateway and applications running as the OS user selected.
- Identify a valid OS user to perform the Management Gateway installation and use it
as value for the
RUN_AGENT_AS_USER
variable.Oracle recommends that the selected OS user should have least privileges and no login shell.id -un <username>
Example 1:
Theid -un myexistinguser
myexistinguser
OS user exists. The output returns the value of the selected user and looks similar to the following:
Example 2:myexistinguser
Theid -un mytestuser2
mytestuser2
OS user doesn't exist and it's not a valid user. The output returns no user value and looks similar to the following:.id: mytestuser2: no such user
- Identify the user's primary group to use as value for the
AGENT_USER_GROUP
variable.Ensure the value forAGENT_USER_GROUP
is the primary user group of the selected OS user.Note
Using a secondary group is not supported and it can result in a corruption of the Management Gateway.id -gn <username>
Example:id -gn myexistinguser
The output looks similar to the following:staff
Set Environment Variables and Install Management Gateway
- Set the following environment
variables:
Example:RUN_AGENT_AS_USER=<selected_OS_user_for_ManagementGateway_installation> AGENT_USER_GROUP=<OS_primary_group_of_selected_OS_user>
RUN_AGENT_AS_USER=myexistinguser AGENT_USER_GROUP=staff
- Ensure the above environment variable are accessible by the
root
OS user.By default, the environment variables are not shared with the
root
user. - Verify the environment variables are set properly by running the following:
For example, the output looks like the following:sudo su echo $RUN_AGENT_AS_USER echo $AGENT_USER_GROUP
myexistinguser staff
Ifroot
is unable to access the environment variables, edit/etc/sudoers
file and add the following:Defaults env_keep+=RUN_AGENT_AS_USER Defaults env_keep+=AGENT_USER_GROUP
The above ensures the
RUN_AGENT_AS_USER
andAGENT_USER_GROUP
environment variables are preserved and accessible by theroot
user.After updating the
/etc/sudoers
file, set the environment variables again and verifyroot
can access the environment variables. -
Once the verification is complete, you can start the Management Gateway installation: Log in as
root
, set the environment variables, and then start the Management Gateway installation.Depending on your preferred method, you can follow the instructions from Install Management Gateway on Linux RPM file or Install Management Gateway on Linux ZIP file.
For example, follow the instructions from Install Management Gateway on Linux RPM file. In this case, skip step 1 since you are already
root
and there's no need ofsudo
privileges. Start at step 2:rpm -ivh <rpm_file_name.rpm>