Getting Started with OS Management

The following sections describe how to get started with the OS Management service.

General Workflow for Setting Up Managed Instances

  1. Review the list of Oracle-provided images that support the OS Management service. See Supported Images.
  2. Review the prerequisites for setting up managed instances. See Prerequisites.
  3. Set up your policies for the OS Management service. See Setting Up Policies for OS Management.
  4. 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.
  5. Verify the status of the OS Management Service Agent plugin. See Verifying the Status of the OS Management Service Agent Plugin.
  6. Start using the OS Management service to manage your instances. See What to Do Next.

Supported Images

OS Management is supported on the following Oracle Linux and Windows platform images and on custom images based on these supported images. For more information about these images, see Oracle-Provided Images.

Oracle Linux
  • Oracle Linux 6 and later
  • Oracle Linux 7 and later
  • Oracle Linux 8 and later
Important

  • For Oracle Linux 8, the OS Management service does not support updating application streams, also known as Appstreams or module streams. For more information, see Known Issues.

  • The OS Management service is not supported on Oracle Autonomous Linux images. For more information, see Known Issues.

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

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

Prerequisites

Important

OS Management is not available as an Always Free service on the Oracle Cloud Free Tier. For more information about Always Free services, see Oracle Cloud Infrastructure's Free Tier.

  • Images: You must be using a supported image. For more information, see Supported Images.
  • Regions: The OS Management service must be available in the region. For more information, see Availability.
  • IAM policies: You must set up the required IAM policies for the OS Management service. For more information, see Setting Up Policies for OS Management.
  • Security Lists (Windows instances only): Your security lists or network rules must be defined to allow access to the Windows update server. For more information, see Windows OS Updates for Windows Images.
  • Service gateways or public IP addresses: Your instances must be attached 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: The Oracle Cloud Agent software must be installed on the instance. Oracle Cloud Agent is installed by default 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: For the instance to be able to use the OS Management service, the OS Management Service Agent plugin must be enabled on the instance and plugins must be running. For more information about how to enable and run plugins, see Managing Plugins with Oracle Cloud Agent.

Setting Up Policies for OS Management

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

Note

  • The policies can be set at the tenancy or compartment level. You must have the required privileges to create the policy. If you do not have required privileges, you should 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.
To allow instances to use the OS Management service

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

  1. Create a dynamic group that contains the set of instances to be managed by the OS Management service. For more information about creating dynamic groups, see Managing Dynamic Groups.
  2. Add a rule for the dynamic group defining the set of instances to be permitted in the policy.
    Note

    Be sure to specify the compartment OCID of the compartment within which the instances exist.

    For example:

    ANY {instance.id = 'ocid1.instance.oc1.iad..exampleuniqueid1', instance.compartment.id = 'ocid1.compartment.oc1..exampleuniqueid2'}

    You can add one or more rules to define the instances to be permitted in the policy.

  3. Create a policy that grants instances access to the OS Management service.
    Note

    The policy grants access to the instances that are members of the dynamic group you created in the first step.

    For example, to create this policy in a compartment inside the tenancy:

    ALLOW dynamic-group <dynamic_group_name> to use osms-managed-instances in compartment <compartment_name>
  4. Create a policy granting instances of that dynamic group permission to retrieve their details for authorization purposes.

    For example, to create this policy in a compartment inside the tenancy:

    ALLOW dynamic-group <dynamic_group_name> to read instance-family in compartment <compartment_name>
  5. Restart the Oracle Cloud Agent
    To restart the Oracle Cloud Agent on Oracle Linux instances:
    1. Log in to your instance. See Connecting to an Instance.
    2. Restart the Oracle Cloud Agent service.
      # sudo systemctl restart oracle-cloud-agent.service
    To restart the Oracle Cloud Agent on Windows instances:
    1. Log in to your instance. See Connecting to an Instance.
    2. Open Windows PowerShell and Run as Administrator.
    3. Restart the Oracle Cloud Agent service.
      PS C:\Users\opc> Restart-Service OCA
To allow the OS Management service to emit metrics

For a managed instance to emit metrics, you must first create a policy to allow the OS Management service permission to read instance information in the tenancy.

For example:

ALLOW service osms to read instances in tenancy

For more information about metrics for OS Management, see OS Management Metrics.

Enabling OS Management for a New Compute Instance

To create a managed instance using the Console
  1. 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.
  2. Enable the OS Management Service Agent plugin.

    Oracle Linux 6, Oracle Linux 7, and Windows
    1. Click Show Advanced Options.
    2. On the Oracle Cloud Agent tab, select the OS Management Service Agent check box. This check box is selected by default.
      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.

    Oracle Linux 8

    Proceed to the next step to create the Oracle Linux 8 instance.

  3. Click Create.

    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.
To create a managed instance 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.

  1. Ensure that the instance has either a public IP address or a service gateway, as described in the prerequisites.
  2. Use the LaunchInstance operation. Include the following parameters:
    {
      "agentConfig": {
        "isManagementDisabled": false,
        "pluginsConfig": [
          {
            "name": "OS Management Service Agent",
            "desiredState": "ENABLED"
          }
        ]
      }
    }
  3. 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.

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

To enable the OS Management Service Agent plugin on an existing instance using the Console
Note

For Oracle Linux 8 instances, you must first manually enable the OS Management Service Agent plugin before you can use the Console to enable or disable the plugin.

  1. Install the Oracle Cloud Agent software, if it is not already installed.
  2. Open the navigation menu. Under Core Infrastructure, go to Compute and click Instances.
  3. Click the instance that you're interested in.
  4. Click the Oracle Cloud Agent tab.
  5. 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.

  6. 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.
To enable the OS Management Service Agent plugin on an existing instance using the API
  1. Install the Oracle Cloud Agent software, if it is not already installed.
  2. Use the LaunchInstance operation. Include the following parameters:
    {
      "agentConfig": {
        "isManagementDisabled": false,
        "areAllPluginsDisabled": false,
        "pluginsConfig": [
          {
            "name": "OS Management Service Agent",
            "desiredState": "ENABLED"
          }
        ]
      }
    }
  3. Ensure that the instance has either a public IP address or a service gateway, as described in the prerequisites.
  4. 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

To disable the OS Management Service Agent plugin using the Console
  1. Open the navigation menu. Under Core Infrastructure, go to Compute and click Instances.
  2. Click the instance that you're interested in.
  3. Click the Oracle Cloud Agent tab.
  4. 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.

Tip

To restore the yum configuration in Oracle Linux instances after disabling the OS Management Service Agent plugin, log in to your instance and unregister the instance from the OS Management service using the sudo osms unregister command.
To disable the OS Management Service Agent plugin using the API
Use the LaunchInstance operation. Include the following parameters:
{
  "agentConfig": {
    "isManagementDisabled": false,
    "areAllPluginsDisabled": false,
    "pluginsConfig": [
      {
        "name": "OS Management Service Agent",
        "desiredState": "DISABLED"
      }
    ]
  }
}
Tip

To restore the yum configuration in Oracle Linux instances after disabling the OS Management Service Agent plugin, log in to your instance and unregister the instance from the OS Management service using the sudo osms unregister command.

Managing the OS Management Service Agent Plugin for Oracle Linux 8 Instances

Note

To enable the OS Management Service Agent plugin in Oracle Linux 8 instances
  1. Log in to your instance. See Connecting to an Instance.
  2. Install the Oracle Cloud Agent software, if it is not already installed.
  3. Run the following sed utility script to enable the OS Management Service Agent plugin.
    sudo sed -i.saved -e '/^  osms:/,/^  [a-z]*:/{
    s/\(.*disabled:.*\)true/\1false/
    /^.*disableByOs:$/,/^  [a-z]*:/{
    /^.*-.*Oracle Linux Server.*:$/d
    /^.*-.*8.x/d}}' /etc/oracle-cloud-agent/agent.yml
    This script updates the osms configuration in the /etc/oracle-cloud-agent/agent.yml file as follows:
    • Changes the value for the disabled: parameter from true to false.
    • Removes the following lines from the disableByOS: section:
       - Oracle Linux Server:
            - 8.x
    Tip

    This script also backs up the configuration file to a file named agent.yml.saved. You can use the backup file to restore the agent.yml to the previous version of the file.
  4. Restart the Oracle Cloud Agent service.
    sudo systemctl restart oracle-cloud-agent.service

    The OS Management Service Agent plugin can now be managed using the Console or API.

  5. Proceed to Verifying the Status of the OS Management Service Agent Plugin.
To disable the OS Management Service Agent plugin in Oracle Linux 8 instances
  1. Log in to your instance. See Connecting to an Instance.
  2. Run the following sed utility script to enable the OS Management Service Agent plugin.
    sudo sed -i.saved -e '/^  osms:/,/^  [a-z]*:/{s/\(.*disabled:.*\)false/\1true/}' /etc/oracle-cloud-agent/agent.yml
    This script updates the osms configuration in the /etc/oracle-cloud-agent/agent.yml file as follows:
    • Changes the value for the disabled: parameter from false to true.
    Tip

    This script also backs up the configuration file to a file named agent.yml.saved. You can use the backup file to restore the agent.yml back to the previous version of the file.
  3. Restart the Oracle Cloud Agent service.
    sudo systemctl restart oracle-cloud-agent.service
  4. Unregister the instance from the OS Management service.
    sudo osms unregister
  5. Proceed to Verifying the Status of the OS Management Service Agent Plugin.

Verifying the Status of the OS Management Service Agent Plugin

To verify the status of the OS Management Service Agent plugin in Oracle Linux instances
Important

The OS Management Service Agent plugin requires Oracle Cloud Agent 1.2.0 or later.
  1. Log in to your instance. See Connecting to an Instance.
  2. 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>
    
  3. Verify the yum configuration.
    ls /etc/yum.repos.d
    1. Check that the existing yum repository configuration is disabled.
    2. 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
  4. 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.

To verify the status of the OS Management Service Agent plugin in Windows instances
  1. Log in to your instance. See Connecting to an Instance.
  2. 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: