Oracle Cloud Infrastructure Documentation

Install Management Gateway

Follow these instructions to install the management gateway.

Download Management Gateway Software

Perform the following steps to download the gateway software:

  1. On the Management Agents home page, click the Downloads and Keys from the left menu to view the Software Download pane.

    The Software Download pane is displayed at the top of the page.

  2. The Software Download pane lists all the software available to download for the Management Agent and Management Gateway.

    Select the operating system that the Management Gateway will be installed on from the Download column.

  3. Click the link specific to your operating system to download the Management Gateway software file.

    For example, click on Gateway for LINUX for Linux or Gateway for WINDOWS for Windows.

Downloads and Keys page that shows the Software Download at the top with a link to download the software file.

The management gateway software file is now saved on your host.

To verify the file integrity, check if the value of the SHA-256 Checksum column matches the output of the following command: sha256sum <download_file.rpm>

Note

The Gateway software image download URL is available only via agent-image list CLI command or ListManagamentAgents API with valid OCI authentication. For details, see Download the Gateway Software Using CLI.

Download the Gateway Software Using CLI

To download Management Gateway software using CLI, do the following:
  1. Obtain the object-url value using the agent-image list CLI command with the --install-type GATEWAY option.
    oci management-agent agent-image list --compartment-id <tenancyId> --install-type GATEWAY

    The return object-url value is similar to the following:

    https://objectstorage.<region_identifier>.oraclecloud.com/n/<namespace>/b/<bucketName>/o/Linux-x86_64/latest/oracle.mgmt_gateway.rpm

    From the above, make a note of the <namespace> and <bucketName> values.

  2. Download the Management Gateway software with OCI authenticated principal using the <namespace> and <bucketName> values from Step 1:
    oci os object get --namespace <namespace> --bucket-name  <bucketName> --name Linux-x86_64/latest/oracle.mgmt_gateway.rpm  --file oracle.mgmt_gateway.rpm

    To verify the file integrity, check if the value of the SHA-256 Checksum column matches the output of the following command: sha256sum <download_file>

Oracle Cloud Infrastructure (OCI) Command Line Interface (CLI) is a command line interface tool. For more information, see Command Line Interface (CLI).

Note

To obtain the object-url value, you can also use the Management Agent API ListManagementAgentImages with the installType=GATEWAY option.

Create an Install Key

You need to create an install key before performing the Management Gateway installation.

An install key is issued against your identity domain and validates the authenticity of the installation. Ensure you have it created before starting the Management Gateway installation process.

For details on how to create an install key, see Create Install Key.

Note

This step can be done only once. You can use the same install key for Management Gateway and Management Agent installations.

Configure a Response File for Management Gateway

The Management Gateway installation script uses a response file to read the parameters specific to your environment.

Review Management Gateway Parameters

A response file containing the gateway parameters is required when executing the gateway setup script.

The following section describes the parameters supported in the response file:

Table 7-2 Response File Parameters

Parameter Name Parameter Type Description
ManagementAgentInstallKey Mandatory Install key required to validate the identity of the domain and the authenticity of the installation.
AgentDisplayName Optional The display name for the gateway that's being installed. This is a unique value. If it's not specified, the system will assign a default value.
BatchingEnabled Optional It enables the batching feature during the Management Gateway installation.

Use BatchingEnabled=true to enable it and provide a better and quicker management of the logging uploads to the Logging Analytics service.

CredentialWalletPassword Optional Password of the gateway wallet when the user provides a custom password for the wallet to store sensitive information.
The password minimum length is 8 characters with the following specifications:
  • At least one lowercase character (a-z)
  • At least one uppercase character (A-Z)
  • At least one digit (0-9)
  • At least one special character from the following list: '!', '@', '#', '%', '^', '&', '*'

All characters from the password must be from the characters defined above. For example, if the password has the $ character as part of the password, it will fail the validity check since $ is not among the special characters listed above.

GatewayPort Optional The port number used by the agents, including Management Agents, when connecting to the Management Gateway. If this port number is not specified, the value will be set to 4480 by default.
GatewayUsername Optional The username used to authenticate with the Gateway server. If it's provided, all clients need to provide this username for authentication. If it's not provided, authentication won't be required for the gateway.
GatewayPassword Optional The password used to authenticate with the Gateway server. If it's provided, all clients need to provide this password for authentication. If it's not provided, authentication won't be required for the gateway.
GatewayCertOcid Optional

OCID of the OCI certificate which will be used for Gateway HTTPS support.

The certificate must be in the same compartment as the one the Gateway is being installed into.
GatewayCertCommonName Optional User provided Fully Qualified Domain Name (FQDN) of Management Gateway host which will be used as "Common Name" during the automatic certificate creation process (See Automatic Certificate Creation Process) as part of the installation.

By default Management Gateway defaults to hostname -f as the value for this property.

ProxyHost Optional Host name or address of the external-facing proxy or firewall. The Management Gateway will use this proxy host (server) to connect to OCI.

If it's provided, the ProxyPort must also be provided.

ProxyPort Optional Proxy server port number of the external-facing proxy or firewall. If it's provided, ProxyHost must also be provided.
ProxyUser Optional User name to authenticate with the external-facing proxy or firewall. If it's provided, ProxyPassword must also be provided.
ProxyPassword Optional User password to authenticate with the external-facing proxy or firewall. If it's provided, ProxyUser must also be provided.
ProxyRealm Optional The authentication realm for external-facing proxy or firewall.
DefinedTags = [{"namespace1":{"<key1>":"<value1>"}}, {"namespace2":{"<key2>":"<value2>"}}] Optional The tag metadata association if using tags in OCI. The tag administrator creates and manages all the tags that the users apply to resources. The users should have defined tag policies.

Tag namespace is a container for your tag keys. The tag key is a key within your namespace, you must create tag keys for defined tags in a namespace.

For defined tags, the tag value has a type which it can be either a string or a list of strings. While defining the tag value type, if the type defined was a string then any value can be entered. Whereas, if it was a list of strings, this value has to be one of the strings from that list.
FreeFormTags = [{"<key1>":"<value1>"}, {"<key2>":"<value2>"}] Optional The tag metadata association if using tags in OCI.

It consists of a key and a value. Key is any name you use to refer to the tag. Value is the value that the user applying the tag adds to the tag key.

For High Availability, it's recommended to configure this parameter. For details, see Configure a Response File for Management Gateway High Availability.

For Associated Agent, if there's a Management Agent connecting via this Management Gateway then add a tag with name "GatewayGroup".

For example: "GatewayGroup":"<User_Defined_ClusterName>

Create a Response File for Management Gateway Installation

Before proceeding, ensure you have reviewed and understood the information provided in Review Management Gateway Parameters.

To install and configure gateways, you need to create a response file and execute a script using the newly created response file which will point the gateway to the correct OCI region and allow a resource to be created for the gateway.

To create a response file, use one of the following options:

Option 1: Download a response file template to create a response file

You can download a template file containing the gateway parameters which can be saved and used as a response file during the gateway installation.

To download a response file template, use the Download Key to File menu option from the Install Keys list.

  • Click Download and Keys from the left menu to open the Install Keys pane. From the list of install keys, select the key that you want to download.

  • On the right side of the selected key, click the action menu Action Menu and select Download Key to File.

    A file is downloaded. For more information, see Download Install Key.

When downloading the install key to a file, the downloaded file contains various parameters, including the value of the specific install key.

After downloading the file, you need to customize it according to your environment:
  • Open the file using a text editor, review it and edit the mandatory gateway parameters. See Review Management Gateway Parameters.
  • Remove the Service.plugin.* parameter. This is an agent-specific parameter. It's only used for agent installations.
  • Uncomment (remove the # symbol from the start of the line) the gateway parameters that you require for your specific gateway configuration and update the gateway parameters values. For example, the following parameters: GatewayPort, GatewayUsername and GatewayPassword should be added to the file.
  • Comment out (add the # symbol at the start of the line) or remove the parameters that you don't require for your specific gateway configuration.
  • Save the updated response file. For example, it can be saved as gateway.rsp response file.

Option 2: Create a response file using a text editor

You can create a response file manually using a text editor. For example, you can create a file using your preferred text editor, add the gateway parameters required for your gateway configuration to the response file and save it. For example, the response file can be saved as gateway.rsp.

Sample of gateway.rsp response file:
managementAgentInstallKey = MS4wLHVzLWFzaGJ1cm4tMSxvY2lkMS50ZW5hbmN5

After creating the response file using any of the above options, check the file permissions and ensure it has read permissions for mgmt_agent user.

Install Management Gateway

Install Management Gateway on Linux RPM file

To install the Management Gateway software on Linux, perform the following steps:

  1. Login as a user with sudo privileges.

  2. Install the Management Gateway software.

    Navigate to the directory where you have downloaded the Management Gateway RPM file and run the following command to install the RPM file: 
    sudo rpm -ivh <rpm_file_name.rpm>

    For example: sudo rpm -ivh oracle.mgmt_gateway-<VERSION>.rpm

    The output will look similar to the following: 
    
Preparing...        ################################# [100%]
Checking pre-requisites
     Checking if any previous gateway service exists        
Checking if OS has systemd or initd
     Checking available disk space for gateway install
     Checking if /opt/oracle/mgmt_agent directory exists
     Checking if 'mgmt_agent' user exists
     Checking Java version
             JAVA_HOME is not set or not readable to root
             Trying default path /usr/bin/java
            Java version: 1.8.0_282 found at /usr/bin/java
     Checking gateway version
Updating /  installing...
   1:oracle.mgmt_gateway-<VERSION>################################# [100%]

Executing install
        Unpacking software zip
        Copying files to destination dir (/opt/oracle/mgmt_agent)
        Initializing software from template
        Checking if JavaScript engine is available to use
        Creating 'mgmt_gateway' daemon        
        Gateway Install Logs: /opt/oracle/mgmt_agent/installer-logs/installer.log.0

        Setup gateway using input response file (run as any user with 'sudo' privileges)
        Usage:
                sudo /opt/oracle/mgmt_agent/agent_inst/bin/setupGateway.sh opts=[FULL_PATH_TO_INPUT.RSP]

         Gateway install successful
    The installation process does the following:
    • A new user called mgmt_agent is created. This will be the Management Gateway user. If mgmt_agent user already exists, the installation process will use it to install the gateway software.
    • All gateway files are copied and installed by mgmt_agent user. The install base directory is the directory where the gateway is installed. The directory is created as part of the gateway installation process under /opt/oracle/mgmt_agent.
    • By default, the mgmt_gateway service/daemon is enabled and started automatically after the gateway installation.
    Log files from the gateway installation are located under /opt/oracle/mgmt_agent/installer-logs directory. To view the log files or any other installation files, login as mgmt_agent user running the following:
    sudo -u mgmt_agent sh
  3. Configure the Management Gateway by running the setupGateway.sh script using a response file. 
    sudo /opt/oracle/mgmt_agent/agent_inst/bin/setupGateway.sh opts=<full_path_of_response_file>
    The output will look similar to the following: 
    sudo /opt/oracle/mgmt_agent/agent_inst/bin/setupGateway.sh opts=<user_home_directory>/gateway.rsp

Executing configure
       Parsing input response file
       Validating install key
       Generating communication wallet
       Generating security artifacts
       Registering Management Gateway
               Found service plugin(s): [GatewayProxy]

Starting gateway...
Gateway started successfully

Starting plugin deployment for: [GatewayProxy]
Deploying service plugin(s)......Done.
        GatewayProxy : Successfully deployed external plugin

Gateway setup completed and the gateway is running.
In the future gateway can be started by directly running: sudo systemctl start mgmt_gateway

Please make sure that you delete <user_home_directory>/gateway.rsp or store it in secure location.

Creating Wallets
Wallets created successfully
Waiting for Gateway to start...
Gateway Proxy started successfully

For more information about creating response files, see Create a Response File for Management Gateway Installation.

Install Management Gateway on Linux ZIP file

To install the management gateway software on Linux using a ZIP file, perform the following steps:
Note

The default installation location is under the /opt volume. If you prefer to use an external volume to install the Management Gateway, see Install Management Gateway on an External Volume using Linux ZIP File.

  1. Extract the Management Gateway software.

    Navigate to the directory where you have downloaded the Management Gateway software ZIP file and unzip it to any preferred location.

  2. Login as a user with sudo privileges.

  3. Install and set up the Management Gateway by running the installer.sh script providing a response file. For information about how to create a response file, see Create a Response File.

    Navigate to the directory where you unzipped the Management Gateway software ZIP file and run the following:
    sudo ./installer.sh

    For example: sudo ./installer.sh

    The output will look similar to the following: 
    sudo ./installer.sh
Checking pre-requisites    
    Checking if any previous gateway service exists    
    Checking if OS has systemd or initd    
    Checking available disk space for gateway install    
    Checking if /opt/oracle/mgmt_agent directory exists    
    Checking if 'mgmt_agent' user exists        
        'mgmt_agent' user already exists, the gateway will proceed installation without creating a new one.    
    Checking Java version        
        JAVA_HOME is not set or not readable to root        
        Trying default path /usr/bin/java        
        Java version: 1.8.0_272 found at /usr/bin/java    
    Checking agent version 

Executing install    
    Unpacking software zip    
    Copying files to destination dir (/opt/oracle/mgmt_agent)    
    Initializing software from template    
    Checking if JavaScript engine is available to use    
    Creating 'mgmt_gateway' daemon    
    Gateway Install Logs: /opt/oracle/mgmt_agent/installer-logs/installer.log.0    
    Setup gateway using input response file (run as any user with 'sudo' privileges)    
    Usage:        
        sudo /opt/oracle/mgmt_agent/agent_inst/bin/setupGateway.sh opts=[FULL_PATH_TO_INPUT.RSP] 

Gateway install successful
  4. Configure the Management Gateway by running the setupGateway.sh script using a response file.
    sudo /opt/oracle/mgmt_agent/agent_inst/bin/setupGateway.sh opts=<full_path_of_response_file>
    The output will look similar to the following:
    sudo /opt/oracle/mgmt_agent/agent_inst/bin/setupGateway.sh opts=/u01/oracle/management_agent/input.rsp
Validating response file
Successfully validated response file
/opt/oracle/mgmt_agent/agent_inst/bin/setupAgent.sh opts=/u01/oracle/management_agent/input.rsp 

Executing configure     
    Parsing input response file        
    Validating install key    
    Generating communication wallet    
    Generating security artifacts    
    Registering Management Gateway        
        Found service plugin(s): [GatewayProxy] 

Starting gateway...
Gateway started successfully 

Starting plugin deployment for: [GatewayProxy]
Deploying service plugin(s).........Done.    
    GatewayProxy : Successfully deployed external plugin 

Gateway setup completed and the gateway is running.
In the future gateway can be started by directly running: sudo systemctl start mgmt_gateway
Please use OCI CLI or OCI Management Agent console to validate the successful activation of your agent. 

Please make sure that you delete /u01/oracle/management_agent/input.rsp or store it in secure location. 

Checking for plugin to be deployed
Plugin deployed successfully
Setting up Gateway
Creating gateway system properties file
Creating properties file
Creating or validating certificates
Waiting for Management Gateway to create or validate certificates ...
Creating wallets
Wallets created successfully
Waiting for Management Gateway to setup ...
Management Gateway Plugin set up successfully.

For more information about creating response files, see Create a Response File for Management Gateway Installation.

Install Management Gateway on an External Volume using Linux ZIP File

In some Linux environments, the /opt volume has limited disk space and can't be used to install software. In those cases, you can install the Management Gateway on an external volume using the Linux ZIP file and creating a symbolic link.

To install Management Gateway on an external volume on Linux, do the following:

  1. Create the Management Gateway install directory on an external volume.
    For example: 
    sudo mkdir -p /devext/oracle/mgmt_agent

    In the above example, /devext is an external volume.

  2. Create a symbolic link in the /opt/oracle directory to point to the external volume.

    Before running the below command, confirm the directory /opt/oracle already exists.

    For example:
    sudo ln -s /devext/oracle/mgmt_agent /opt/oracle/mgmt_agent
  3. Confirm the Management Gateway software Linux ZIP file has been downloaded. For details, see Download the Agent Software.
  4. Switch to a root shell, set the environment variable OPT_ORACLE_SYMLINK = true, and install the Management Gateway software as root user.
    sudo /bin/bash
export OPT_ORACLE_SYMLINK=true
./installer.sh
    For example:
    sudo /bin/bash
export OPT_ORACLE_SYMLINK=true
./installer.sh
  5. After the installation process is completed, verify the mgmt_agent Linux user is the owner of the Management Gateway install location.
    stat -c '%U' /opt/oracle/mgmt_agent
mgmt_agent

sudo stat -c '%U' /opt/oracle/mgmt_agent/agent_inst
mgmt_agent

Install Management Gateway on Windows

To install the Management Gateway software on Windows, perform the following steps:

  1. Extract the Management Gateway software.

    Navigate to the directory where you have downloaded the Management Gateway software ZIP file and unzip it to any preferred location.

  2. Login as an Administrator user and open a Command Prompt window.

  3. Install the Management Gateway by running the installer.bat script. 
    installer.bat
    The output will look similar to the following: 
    Checking pre-requisites
        Checking if previous gateway service exists
        Checking if C:\Oracle\mgmt_agent\agent_inst directory exists       
        Checking if C:\Oracle\mgmt_agent\agent_inst\plugins directory exists
        Checking Java version
                Java version: 1.8.0_371 found at C:\Program Files\Java\jdk-1.8
        Checking if C:\Oracle\mgmt_agent\231214.1713 directory exists
Executing install
        Unpacking software zip
        Copying files to destination dir (C:\Oracle\mgmt_agent) 
        Initializing software from template
        Checking if JavaScript engine is available to use
        Creating mgmt_gateway service
Gateway install successful
Setup gateway using input response file
       Usage:         
       C:\Oracle\mgmt_agent\agent_inst\bin\setupGateway.bat [FULL_PATH_TO_INPUT.RSP]
  4. Configure the Management Gateway by executing the setupGateway.bat script using the response file.
    <Management_Agent_path>\setupGateway.bat <full_path_of_response_file>
    For example:
    C:\Oracle\mgmt_agent\agent_inst\bin\setupGateway.bat c:\tmp\input.rsp
    The output looks similar to the following:
    Validating response file
Validating certificate properties
Successfully validated response file

Executing configure     
        Parsing input response file
        Validating install key       
        Generating communication wallet
        Generating security artifacts     
        Registering Management Gateway
                Found service plugin(s): [GatewayProxy]

The Oracle Management Gateway service is starting...
The Oracle Management Gateway service was started successfully.

Starting plugin deployment for: [GatewayProxy]
Deploying service plugin(s)...Done.
        GatewayProxy : Successfully deployed external plugin

Management Gateway setup completed and is running
In the future agent can be started by directly running: NET START mgmt_gateway
Please use OCI CLI or OCI Management Agent console to validate the successful activation of your agent."

Please make sure that you delete C:\tmp\input.rsp or store it in secure location.

Checking for plugin to be deployed
Plugin deployed successfully
Setting up Gateway
Creating gateway system properties file
Creating properties file
Creating or validating certificates
Waiting for Management Gateway to create or validate certificates ...
Waiting for Management Gateway to create or validate certificates ...
Waiting for Management Gateway to create or validate certificates ...
Waiting for Management Gateway to create or validate certificates ...
Waiting for Management Gateway to create or validate certificates ...
Wallets created successfully
Waiting for Management Gateway to setup ...
Management Gateway Plugin set up successfully.
The gateway installation process does the following:
  • A new directory is created as part of the agent installation process: C:\Oracle\mgmt_agent.
  • The agent install base directory is the directory where the gateway will be installed.

    By default, the gateway is installed under the C:\Oracle directory. The default directory can be changed by setting the AGENT_INSTALL_BASEDIR environment variable before running the installer.bat script.

  • Log files from the Management Gateway installation are located under C:\Oracle\mgmt_agent\installer-logs and C:\Oracle\mgmt_agent\plugins\GatewayProxy\stateDir\logs directories.

Verify the Management Gateway Installation

Verify the Management Gateway Installation Using User Interface

To verify the agent installation using the user interface, perform the following steps:

  1. On the main Management Agents page, click Agents from the left menu.

    The Agents and Gateways page is displayed with a list of all agents and gateway installed.

    To see only the gateways, go to the left menu and use the Filters: Use the Install Type filter and select Gateway.

    All the gateways are displayed.

  2. From the Agents and Gateways list, look for the gateway that was recently installed using the Created column which displays the date of the agent installation or the Host column which displays the host name where the gateway was installed.

Verify the Management Gateway Installation Using Command Line Interface

Verify the Management Gateway Installation Using Command Line Interface on Linux

  1. Login to the host using a user with sudo privileges.
  2. Run the following command:

    For Oracle Linux 6: sudo /sbin/initctl status mgmt_gateway

    For Oracle Linux 7: sudo systemctl status mgmt_gateway

    For more details, check log file: /opt/oracle/mgmt_agent/plugins/GatewayProxy/stateDir/log/mgmt_gateway.log.

Verify the Management Gateway Installation Using Command Line Interface on Windows

  1. Login to the host
  2. Run the following command:
    sc query mgmt_gateway

    For more details, check log file: /opt/oracle/mgmt_agent/plugins/GatewayProxy/stateDir/log/mgmt_gateway.log.