Getting Started with OS Management

General Workflow for Setting Up Managed Instances

Review the list of Oracle-provided images that support the OS Management service. See Supported Environments.
Review the prerequisites for setting up managed instances. See Prerequisites.
Set up your IAM policies for the OS Management service. See Setting Up IAM Policies for OS Management.
Enable OS Management on a new or existing instance. See Enabling OS Management for a New Compute Instance and Enabling the OS Management Service Agent Plugin for an Existing Compute Instance.
Verify the status of the OS Management Service Agent plugin. See Verifying the Status of the OS Management Service Agent Plugin.
Start using the OS Management service to manage your instances. See What to Do Next.

Supported Environments

OS Management is included on the following Oracle Linux and Windows platform images. For more information about platform images, see Platform Images.

In addition, you can configure custom images for OS Management by installing the required Oracle Cloud Agent and enabling the OS Management Service Agent plugin. For more information on adding the Oracle Cloud Agent to custom images, see Managing Plugins with Oracle Cloud Agent.

Note

OS Management uses updates and content from the OS vendor. Ensure that you are using a supported OS release when using custom images.

Oracle Linux

Oracle Linux 9 and later.
Oracle Linux 8 and later.
Oracle Linux 7 and later.
Oracle Linux 6 and later.
Oracle Autonomous Linux, beginning with the August 2021 platform image. For more information, see Oracle Autonomous Linux.

Important

Beginning with the Oracle Linux platform images released in April 2024, the OS Management Service Agent plugin is disabled by default in Oracle Cloud Agent 1.40.0 for Oracle Linux instances.
Beginning with the Oracle Linux 8 platform images released in October 2021, the OS Management Service Agent plugin is enabled by default in Oracle Cloud Agent 1.16.0 for Oracle Linux 8 instances.

For Oracle Linux 8 instances that were launched before October 2021 (running Oracle Cloud Agent 1.15.0 or earlier), the OS Management Service Agent plugin is disabled by default. The OS Management Service Agent plugin for disabled Oracle Linux 8 instances remain disabled after being updated to Oracle Cloud Agent 1.16.0.

For disabled Oracle 8 instances, you might see a discrepancy in the status of the OS Management Service Agent plugin after the update to Oracle Cloud Agent 1.16.0. For more information, see Known Issues.
Beginning with Oracle Cloud Agent 1.15.0, the OS Management service is supported on Arm-based Ampere A1 Compute shapes.
Beginning with the Oracle Linux platform images released in September 2020, the OS Management service uses the OS Management Service Agent plugin for all Oracle Linux instances. The OS Management Service Agent plugin replaces the OS Management Service Agent (osms-agent) package. For more information about the OS Management Service Agent plugin, see OS Management Components and Features.

Windows

Windows Server 2012 R2 Standard, Datacenter
Windows Server 2016 Standard, Datacenter
Windows Server 2019 Standard, Datacenter
Windows Server 2022 Standard, Datacenter

Prerequisites

Important

OS Management is not available on the Oracle Cloud Free Tier.

Images: Use a supported image. For more information, see Supported Environments.
IAM policies: Set the required IAM policies for the OS Management service. For more information, see Setting Up IAM Policies for OS Management.
Security Lists (Windows instances only): Define your security lists or network rules to allow access to the Windows update server. For more information, see Windows OS Updates for Windows Images.
Service gateways or public IP addresses (Linux instances only): Attach your instance to a virtual cloud network (VCN) that has one of the following:
- A private subnet with a service gateway that uses the All <region> Services in Oracle Services Network CIDR label.
- A private subnet with a NAT gateway.
- A public subnet with an internet gateway.
For detailed instructions, see Access to Oracle Services: Service Gateway.
Oracle Cloud Agent: Ensure that the Oracle Cloud Agent software is installed and running on the instance. By default, the Oracle Cloud Agent is installed on current Oracle-provided images. For steps to manually install Oracle Cloud Agent on older images, see Installing the Oracle Cloud Agent Software.
OS Management Service Agent plugin: Ensure that the OS Management Service Agent plugin is enabled and running on the instance. By default, the OS Management Service Agent plugin is enabled and running on current Oracle-provided images.

Setting Up IAM Policies for OS Management

This topic explains how to set up the required policies for using the OS Management service.

Note

You must have the required privileges to create the policy. If you do not have required privileges, work with the administrator for your tenancy to either obtain the privileges to create the policies or to have the policies created for you.
For more information about setting up policies for the OS Management service, see Details for the OS Management Service.

Required Dynamic Group

Before you create the required IAM policies for OS Management, you first need to create a dynamic group. A dynamic group can include instances based on instance OCID or include instances that reside in a compartment based on compartment OCID. For more information about dynamic groups, see Managing Dynamic Groups.

When you create a dynamic group, you define the group members in matching rule statements using the rule builder.

Important

A single instance can belong to a maximum of five dynamic groups. A good practice is to reuse the same dynamic group wherever possible across services instead of creating one or more dynamic groups for each service.

When defining matching rules, you set conditions for the matching rule statements:

All of the following (All) includes only instances that match all the statements in the rule.
Any of the following (Any) includes instances that match any of the statements in the rule.

Follow these guidelines when creating matching rule statements:

You can add one or more rules to define the instances to be permitted in the policy.
All statements require that all matching rule statements be true. This condition can cause problems when you add multiple compartments or instances to the group under a single rule or multiple rules. When using All, each rule condition must be met (true); otherwise the request is denied.
Dynamic groups do not support compartment inheritance. Be sure to specify the compartment OCIDs of the compartments where the instances reside.

Tip

The OCID for an instance is displayed on the Instance Details page while the OCID for the compartment is displayed on the Compartments page or by using the oci metadata utility.

After creating the dynamic group, you can create your IAM policy to permit instances to make API calls against the OS Management service.

Required User Group

Before you create the required IAM policies for OS Management, you need to create a user group for users. This user group is used in a policy to allow users to interact with the OS Management service. For more information about user groups, see Managing Groups.

Example: Dynamic Group

Provides a dynamic group example to help you understand the use of Any and All conditions in a matching rule statement.

Understanding Any and All Conditions

Policy Rule: When using All, for the policy to be true, instances must match all rule statements.

All {instance.id = 'ocid1.instance1.oc1.iad..exampleuniqueid1', instance.compartment.id ='ocid1.compartmentA.oc1..exampleuniqueid2'}

In this example, instance1 (ocid1.instance1.oc1.iad..exampleuniqueid1) must reside in compartmentA (ocid1.compartmentA.oc1..exampleuniqueid2) for the policy to be true. If instance1 is not in compartmentA, the matching statement is false and the service fails.

Using the same example, by changing All to Any, either an instance that matches the OCID for instance1 or an instance in compartmentA would be true.

Any {instance.id = 'ocid1.instance1.oc1.iad..exampleuniqueid1', instance.compartment.id ='ocid1.compartmentA.oc1..exampleuniqueid2'}

Required IAM Policies

For an instance to be registered with the OS Management service, you must create policies that allow instances to use OS Management.

Before you create the IAM policies, you first need to create a dynamic group.

Note

The policy statement uses the default identity domain unless you define the identity domain before the group or dynamic group name (for example, <identity_domain_name>/<dynamic_group_name>). For more information, see Policy Syntax.

Required IAM Policies

You can set the required IAM policies for OS Management either at the tenancy or compartment level.

To apply the required IAM policies for OS Management to the tenacy, use the following policy.

Allow group <group_name> to manage osms-family in tenancy
Allow dynamic-group <dynamic_group_name> to read instance-family in tenancy
Allow dynamic-group <dynamic_group_name> to use osms-managed-instances in tenancy

If the tenancy administrator doesn't permit setting IAM policies at the tenancy level, you can restrict the management of OS Management resources to a compartment. To apply the IAM policy for OS Management only to a compartment inside the tenancy, use the following policies.

Allow group <group_name> to manage osms-family in compartment <compartment_name>
Allow dynamic-group <dynamic_group_name> to read instance-family in compartment <compartment_name>
Allow dynamic-group <dynamic_group_name> to use osms-managed-instances in compartment <compartment_name>

Required IAM Policy for Metrics

To allow the OS Management service to emit metrics, use the following policy.

Important

This policy must be specified at the tenancy level.

Allow service osms to read instances in tenancy

After setting the policies, you must restart the Oracle Cloud Agent.

To restart the Oracle Cloud Agent on Oracle Linux instances:

Log in to your instance. See Connecting to an Instance.
Restart the Oracle Cloud Agent service.
Oracle Linux 9, Oracle Linux 8, and Oracle Linux 7
sudo systemctl restart oracle-cloud-agent.service
Oracle Linux 6
sudo initctl restart oracle-cloud-agent

Enabling OS Management for a New Compute Instance

Using the Console

Follow the steps to create an instance, until the advanced options. Ensure that the instance has either a public IP address or a service gateway, as described in the prerequisites.
Enable the OS Management Service Agent plugin.
Click Show Advanced Options.
On the Oracle Cloud Agent tab, select the OS Management Service Agent check box.
Note

If you're using an older Oracle-provided image or a custom image that is not based on a recent Oracle-provided image, you must manually install the Oracle Cloud Agent software. You can do this by providing a cloud-init script. For more information, see Installing the Oracle Cloud Agent Software. Compare the date of the image to the date listed in Supported Images.
Click Create.
- For Oracle Linux and Windows instances, the Compute instance can be managed using the OS Management service. Proceed to Verifying the Status of the OS Management Service Agent Plugin.
Important

When registering with the OS Management service, Oracle Linux instances subscribe to the default channel list and all other channel subscriptions are disabled. If you need to reenable any of these channels, you can do so using the Console, CLI, or REST APIs. For more information, see Managing Software Sources.

Using the API

Note

If you're using an older Oracle-provided image or a custom image that is not based on a recent Oracle-provided image, you must manually install the Oracle Cloud Agent software. You can do this by providing a cloud-init script. For more information, see Installing the Oracle Cloud Agent Software. Compare the date of the image to the date listed in Supported Images.

Ensure that the instance has either a public IP address or a service gateway, as described in the prerequisites.

Use the LaunchInstance operation. Include the following parameters:

{
  "agentConfig": {
    "isManagementDisabled": false,
    "pluginsConfig": [
      {
        "name": "OS Management Service Agent",
        "desiredState": "ENABLED"
      }
    ]
  }
}

Proceed to Verifying the Status of the OS Management Service Agent Plugin.

Important

When registering with the OS Management service, Oracle Linux instances subscribe to the default channel list and all other channel subscriptions are disabled. If you need to reenable any of these channels, you can do so using the Console, CLI, or REST APIs. For more information, see Managing Software Sources.

Enabling the OS Management Service Agent Plugin for an Existing Compute Instance

Using the Console

Install the Oracle Cloud Agent software, if it is not already installed.
Open the navigation menu, click Compute, and then click Instances.
Click the instance that you're interested in.
Click the Oracle Cloud Agent tab.
For the OS Management Service Agent plugin, toggle the Enable Plugin switch to Enabled, if the switch is disabled.

It takes up to 10 minutes for the change to take effect.

For more information about how to enable and run plugins, see Managing Plugins with Oracle Cloud Agent.
Proceed to Verifying the Status of the OS Management Service Agent Plugin.

Important

When registering with the OS Management service, Oracle Linux instances subscribe to the default channel list and all other channel subscriptions are disabled. If you need to reenable any of these channels, you can do so using the Console, CLI, or REST APIs.

Using the API

Install the Oracle Cloud Agent software, if it is not already installed.

Use the LaunchInstance operation. Include the following parameters:

{
  "agentConfig": {
    "isManagementDisabled": false,
    "areAllPluginsDisabled": false,
    "pluginsConfig": [
      {
        "name": "OS Management Service Agent",
        "desiredState": "ENABLED"
      }
    ]
  }
}

Ensure that the instance has either a public IP address or a service gateway, as described in the prerequisites.
Proceed to Verifying the Status of the OS Management Service Agent Plugin.

Important

When registering with the OS Management service, Oracle Linux instances subscribe to the default channel list and all other channel subscriptions are disabled. If you need to reenable any of these channels, you can do so using the Console, CLI, or REST APIs.

Disabling the OS Management Service Agent Plugin

Using the Console

Open the navigation menu, click Compute, and then click Instances.
Click the instance that you're interested in.
Click the Oracle Cloud Agent tab.
Toggle the Enable Plugin switch to Disabled, if the switch is enabled.

It takes up to 10 minutes for the change to take effect.

For more information about how to enable and run plugins, see Managing Plugins with Oracle Cloud Agent.
Restore the yum configuration in the instance after disabling the OS Management Service Agent plugin.
1. Log in to your instance. See Connecting to an Instance.
2. Unregister the instance from the OS Management service.
```
sudo osms unregister
```

Using the API

Use the LaunchInstance operation. Include the following parameters:

{
  "agentConfig": {
    "isManagementDisabled": false,
    "areAllPluginsDisabled": false,
    "pluginsConfig": [
      {
        "name": "OS Management Service Agent",
        "desiredState": "DISABLED"
      }
    ]
  }
}

Restore the yum configuration in the instance after disabling the OS Management Service Agent plugin.
1. Log in to your instance. See Connecting to an Instance.
2. Unregister the instance from the OS Management service.
```
sudo osms unregister
```

Verifying the Status of the OS Management Service Agent Plugin

Oracle Linux instances

Important

The OS Management Service Agent plugin requires Oracle Cloud Agent 1.2.0 or later.

Log in to your instance. See Connecting to an Instance.
Validate whether your instance can reach the OS Management ingestion service.
```
curl https://ingestion.osms.<region>.oci.oraclecloud.com/
```
For <region>, specify the region identifier (for example, us-phoenix-1). See Regions and Availability Domains for more information about region identifiers.

For example, the following sample output indicates that the instance can successfully reach the OS Management ingestion service.

Note

The 403 Forbidden status code message is expected in the output.
```
<html>
<head><title>403 Forbidden</title></head>
<body bgcolor="white">
<center><h1>403 Forbidden</h1></center>
<hr><center>nginx/1.14.2</center>
</body>
</html>
```

Verify the yum configuration.

ls /etc/yum.repos.d

Check that the existing yum repository configuration is disabled.
Ensure that the *.repo files in the /etc/yum.repos.d directory are backed up to *.repo.osms-backup in the same directory.

For example:

$ ls /etc/yum.repos.d
ksplice-ol7.repo.osms-backup                oracle-linux-ol7.repo.osms-backup
ksplice-uptrack.repo.osms-backup            oracle-softwarecollection-ol7.repo.osms-backup
oci-included-ol7.repo.osms-backup           uek-ol7.repo.osms-backup
oracle-epel-ol7.repo.osms-backup            virt-ol7.repo.osms-backup
oraclelinux-developer-ol7.repo.osms-backup

Verify that the OS Management Service Agent plugin is running on the instance.

ps -elf | grep osms | grep -v grep

For example:

$ ps -elf | grep osms | grep -v grep
4 S root     24269 24245  0  80   0 - 62257 -      Jun30 ?        00:00:00 /usr/bin/sudo -n /usr/libexec/oracle-cloud-agent/plugins/osms/osms-agent
4 S root     24273 24269  0  80   0 -  2165 -      Jun30 ?        00:00:00 /usr/libexec/oracle-cloud-agent/plugins/osms/osms-agent
4 S root     24274 24273  0  80   0 - 406892 -     Jun30 ?        00:50:28 /usr/libexec/oracle-cloud-agent/plugins/osms/osms-agent

Note

If the OS Management Service Agent plugin is not installed or has been stopped, no output is displayed for this command.

After the OS Management Service Agent plugin is running, you have completed the getting started tasks for setting up the managed instance. You can now use the OS Management service to manage the instance. Proceed to What to Do Next.

Windows instances

Log in to your instance. See Connecting to an Instance.
Perform one of the following procedures:
To verify the status of the Oracle Cloud Agent using Windows PowerShell:
1. Open Windows PowerShell.
2. Run the Get-Service OCAOSMS command and verify that the status is running.
  
  For example:
```
PS C:\Users\opc> Get-Service OCAOSMS
Status   Name               DisplayName
------   ----               -----------
Running  OCAOSMS            Oracle Cloud Operating System Manag...
                            
```
To verify the status of the Oracle Cloud Agent using Computer Management:
1. Go to Computer Management.
  Tip
  
  In the Search column, you can get to Computer Management by searching on the keywords: Computer Management or compmgmt.msc.
2. Click Services and Applications and then Services.
3. Verify that the Oracle Cloud Agent service is running.

After the OS Management Service Agent plugin is running, you have completed the getting started tasks for setting up the managed instance. You can now use the OS Management service to manage the instance.

What to Do Next

After setting up managed instances, you can start using the OS Management service to keep those instances up to date with the latest patches and updates.

Common tasks that you perform after creating managed instances include:

Creating managed instance groups. For more information, see Administering Managed Instance Groups.
Managing software sources for Linux instances. For more information, see Managing Software Sources.
Managing Linux packages. For more information, see Managing Linux Packages.
Managing Windows updates. For more information, see Managing Windows Updates.
Managing schedule jobs and work requests. For more information, see Managing Scheduled Jobs and Work Requests.

Oracle Cloud Infrastructure Documentation

Getting Started with OS Management

General Workflow for Setting Up Managed Instances

Supported Environments

Prerequisites

Setting Up IAM Policies for OS Management

Required Dynamic Group

Required User Group

Example: Dynamic Group

Understanding Any and All Conditions

Required IAM Policies

Enabling OS Management for a New Compute Instance

Enabling the OS Management Service Agent Plugin for an Existing Compute Instance

Disabling the OS Management Service Agent Plugin

Verifying the Status of the OS Management Service Agent Plugin

What to Do Next