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