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.

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>


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:


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


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.


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

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.

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.

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

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)
                    sudo /opt/oracle/mgmt_agent/agent_inst/bin/ 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 script using a response file.
    sudo /opt/oracle/mgmt_agent/agent_inst/bin/ opts=<full_path_of_response_file>
    The output will look similar to the following:
    sudo /opt/oracle/mgmt_agent/agent_inst/bin/ 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.

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.