Oracle Cloud Infrastructure Documentation

Management Gateway Administration Tasks

Update Management Gateway Properties

Management Gateway Port

The Management Gateway is configured to accept traffic on a specific port which is specified by using the 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.

After changing the 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.

Note

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 the C:\Oracle\mgmt_agent\plugins\GatewayProxy\stateDir\bin directory.

  1. 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.

  2. 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 the cred.properties file::
      type cred.properties | C:\Oracle\mgmt_agent\plugins\GatewayProxy\stateDir\bin\gateway_credentials.bat -o upsertCredentials

  3. 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 the C:\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
Note

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:

The Management Gateway should be configured with a proxy using the following two properties:
  • ProxyHost
  • ProxyPort
For example:
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.
Note

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

Execute the below command to update the proxy credentials using the above sample file:
  • 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
Note

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.

To enable batching, add the following property in the 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

To upgrade a gateway on Linux, do the following:
  • 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

To upgrade a gateway on Windows, do the following:
  • 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: C:\Users\test_agent>installer.bat -u

    The output looks similar to the following:
    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

Execute the following 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.
Note

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.

The output looks similar to the following: 
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

Note

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) for max 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.

  1. 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:

    id -un myexistinguser
    The myexistinguser OS user exists. The output returns the value of the selected user and looks similar to the following:
    myexistinguser
    Example 2:
    id -un mytestuser2
    The 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
  2. Identify the user's primary group to use as value for the AGENT_USER_GROUP variable.
    Ensure the value for AGENT_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

  1. Set the following environment variables:
    RUN_AGENT_AS_USER=<selected_OS_user_for_ManagementGateway_installation>
AGENT_USER_GROUP=<OS_primary_group_of_selected_OS_user>
    Example:
    RUN_AGENT_AS_USER=myexistinguser
AGENT_USER_GROUP=staff
  2. Ensure the above environment variable are accessible by the root OS user.

    By default, the environment variables are not shared with the root user.

  3. Verify the environment variables are set properly by running the following:
    sudo su
echo $RUN_AGENT_AS_USER
echo $AGENT_USER_GROUP
    For example, the output looks like the following:
    myexistinguser
staff
    If root 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 and AGENT_USER_GROUP environment variables are preserved and accessible by the root user.

    After updating the /etc/sudoers file, set the environment variables again and verify root can access the environment variables.

  4. 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 of sudo privileges. Start at step 2: rpm -ivh <rpm_file_name.rpm>