Install Management Gateway
Follow these instructions to install the management gateway.
Download Management Gateway Software
Perform the following steps to download the gateway software:
-
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.
-
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.
-
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.
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
- 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.
- 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. |
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 |
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:
All characters from the password must
be from the characters defined above. For example, if the
password has the |
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 |
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 |
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 For example: |
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.
-
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 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.
- 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
andGatewayPassword
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
.
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
-
Login as a user with
sudo
privileges. -
Install the Management Gateway software.
Navigate to the directory where you have downloaded the Management GatewayRPM
file and run the following command to install theRPM
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. Ifmgmt_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 asmgmt_agent
user running the following:sudo -u mgmt_agent sh
- A new user called
-
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
ZIP
file, perform the following steps:
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.
-
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. -
Login as a user with
sudo
privileges. -
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 softwareZIP
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
- 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:
- 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. - 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
- Confirm the Management Gateway software Linux
ZIP
file has been downloaded. For details, see Download the Agent Software. - 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
- 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
-
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. -
Login as an Administrator user and open a Command Prompt window.
-
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]
- 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.
- 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 theAGENT_INSTALL_BASEDIR
environment variable before running theinstaller.bat
script. - Log files from the Management Gateway installation are located under
C:\Oracle\mgmt_agent\installer-logs
andC:\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:
-
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 selectGateway
.All the gateways are displayed.
-
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
- Login to the host using a user with
sudo
privileges. - 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
- Login to the host
- 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
.