test

System Administration Guide: Basic Administration

Chapter 17 Working With the Oracle Solaris Auto Registration regadm Command (Tasks)

This chapter describes how to use the regadm command, which is part of the new Oracle Solaris Auto Registration feature as of Oracle Solaris 10 9/10.

Auto Registration is a built-in mechanism that enables configuration data about your system to be gathered and automatically registered with the Oracle Product Registration System for inventory and support purposes. The regadm command-line interface (CLI) can be used by a privileged system administrator to manage the Auto Registration feature and to explicitly register a system, independent of the installation or upgrade process.

Note –

This chapter does not provide detailed information about auto registration processes that are part of an installation or upgrade. Nor does the chapter contain information about which installation methods and configurations support Auto Registration.

For overview information about Auto Registration and details about how the feature works with the installation process, see Oracle Solaris Auto Registration in Oracle Solaris 10 9/10 Installation Guide: Planning for Installation and Upgrade.

The following is a list of the information that is in this chapter:

Oracle Solaris Auto Registration (Overview)

Oracle Solaris Auto Registration is a mechanism that is built into Oracle Solaris 10 9/10. This mechanism enables basic asset information about your system, called a service tag, to be transmitted to the Oracle Product Registration System upon reboot after an installation or an upgrade, and again on subsequent reboots, if any system configuration changes have occurred. The Oracle Product Registration System consists of web services that are deployed on the public Internet. These services are responsible for implementing the registration of a system's assets. Oracle uses this information to improve its products and services. You can also retrieve and use this information to more effectively manage your inventory.

Auto Registration leverages the existing service tag technology that enables a system's assets to be discovered on a network and then registered in a local registry. Service tags contain information about the products that are installed on your system, for example, the OS version and the hardware configuration. Each service tag describes a different product. To enable the sending of service tags, use your My Oracle Support credentials. For more information, see How Your Oracle Solaris 10 9/10 System Is Registered.

For more information about how service tags work, go to http://wikis.sun.com/display/ServiceTag/Download+OS+Service+Tag.

For general information about service tags, see the stclient(1M) man page.

For answers to common questions and information about how to gain initial access to My Oracle Support, go to http://www.oracle.com/us/support/044753.html#SS6.

How Your Oracle Solaris 10 9/10 System Is Registered

Oracle uses support credentials and network connectivity information that is collected before or during an installation or upgrade to associate product registration with a specific user account. Support credentials can also be provided after an installation by using the regadm auth command. See Authenticating a User by Specifying Named Support Credentials. If no support credentials or network connectivity information is specified, the Auto Registration process assumes a direct HTTP network connection (no proxy), and the registration is anonymous.

To register your system by specifying support credentials, you must have either a valid My Oracle Support account or a valid Sun Online account. Support credentials consist of a user name and password that enable you to authenticate to Oracle's support portal and the Oracle Product Registration System.

For information about obtaining a My Oracle Support account, go to http://www.oracle.com/support/premier/myoraclesupport.html.

For information about obtaining a Sun Online account, go to https://reg.sun.com/register.

If you are running Oracle Solaris 10 9/10, you can provide support credentials, as follows:

When and How Service Tag Data Is Transmitted

Auto Registration is managed by the svc:/application/autoreg SMF service. This service runs once at boot time to check for changes in your system's configuration.

If any changes have occurred, the service tag data is automatically sent to the Oracle Product Registration System, as follows:

To obtain information about your registered products, go to https://inventory.sun.com/inventory/data.jsp. For general information about service tags, go to http://wikis.sun.com/display/ServiceTag/Download+OS+Service+Tag.

Managing Auto Registration Configuration

After an installation or upgrade, Auto Registration configuration can be managed by using the regadm command.

After an installation, a privileged system administrator can perform the following tasks by using the regadm command:

For more information, see the regadm(1M) man page.

For task-related information, see Registering Your System by Using the regadm Command.

How the Auto Registration Process Works

During a system reboot, the Auto Registration SMF service checks your system's configuration against the information in the Service Tag Registry to determine whether any changes have occurred since the last reboot. If changes are discovered, a service tag for the newly installed product, for example, the Oracle Solaris 10 9/10 OS, is sent to the Oracle Product Registration System and registered with your recorded support credentials, or anonymously, if no support credentials were provided. The data is transmitted by using a Hypertext Transfer Protocol Secure (HTTPS) connection. If no changes are detected during a reboot, no registration is performed.

Although Auto Registration feature is enabled by default, you can optionally disable the feature. For information, see How to Disable the Auto Registration SMF Service.

Note –

The Auto Registration SMF service runs in global zones only.

In addition to the Auto Registration SMF service, the Auto Registration process consists of several other components that work together to affect auto registration of your system's assets. The following figure illustrates these components and their relationship to each other.

Graphic illustrates components that comprise Oracle Solaris Auto Registration and how the component interact with each other.

Auto Registration consists of the following components:

Getting Started With the regadm Command

The following is information that will help you get started with administering Auto Registration by using the regadm command.

When to Use the regadm Command-Line Interface

The following are situations in which you might need to use the regadm command:

Requirements for Using the regadm Command

The following are the requirements for using the regadm command:

Managing the Auto Registration SMF Service

The Auto Registration feature is managed by an SMF service. This service is enabled by default. You can manually disable the service by using the regadm disable command. The following procedures describe how to manage the Auto Registration SMF service.

Note –

The Auto Registration SMF service runs in a global zone only.

Table 17–1 Managing the Auto Registration SMF Service (Task Map)

Task 

Instructions 

For Information 

Display the status of the Auto Registration SMF service. 

You can use the regadm command to determine if the Auto Registration SMF service is running. Note that the service is enabled by default.

How to Determine If the Auto Registration SMF Service Is Enabled

Disable the Auto Registration SMF service. 

If you do not want to register, or you want to postpone registration, you can optionally disable the Auto Registration SMF service by using the regadm command.

How to Disable the Auto Registration SMF Service

Enable the Auto Registration SMF service. 

If you previously disabled the Auto Registration SMF service, you must enable the service prior to registering your system. 

How to Enable the Auto Registration SMF Service

ProcedureHow to Determine If the Auto Registration SMF Service Is Enabled

  1. Become superuser or assume an equivalent role.

    Roles contain authorizations and privileged commands. For more information about roles, see Configuring RBAC (Task Map) in System Administration Guide: Security Services.

  2. Display the current status of the Auto Registration service.


    # regadm status
Solaris Auto-Registration is currently enabled

ProcedureHow to Disable the Auto Registration SMF Service

The Auto Registration feature enabled by default. You can manually disable the service by using the regadm disable command.

  1. Become superuser or assume an equivalent role.

  2. Display the current status of the Auto Registration service.


    # regadm status
Solaris Auto-Registration is currently enabled

  3. Disable the Auto Registration service.


    # regadm disable

  4. Verify that the service has been disabled.


    # regadm status
Solaris Auto-Registration is currently disabled

ProcedureHow to Enable the Auto Registration SMF Service

  1. Become superuser or assume an equivalent role.

  2. Display the current status of the Auto Registration service.


    # regadm status
Solaris Auto-Registration is currently disabled

  3. Enable the Auto Registration service.


    # regadm enable

  4. Verify that the service has been enabled.


    # regadm status
Solaris Auto-Registration is currently enabled

Configuring the Auto Registration Feature by Using the regadm Command

The regadm command can be used to configure Auto Registration, as well as view configuration details. Note that certain configuration tasks, for example, authentication, must be performed prior to registering your system. For more information, see Tasks That Are Required Prior to Registration.

Table 17–2 Configuring Auto Registration Properties (Task Map)

Task 

Instructions 

For Information 

Display the current Auto Registration configuration. 

Use the regadm list command to display the current Auto Registration configuration. User account credentials, as well as network connectivity information, is displayed by using this command.

Displaying the Current Auto Registration Configuration

Clear the current Auto Registration configuration. 

Use the regadm clear command to reset the current Auto Registration configuration. Note that all properties are cleared during this process.

How to Clear the Current Auto Registration Configuration

Configure HTTP proxy and port settings. 

Use the regadm set command to configure network connectivity information.

How to Configure HTTP Proxy and Port Settings

Configure HTTP proxy authentication settings. 

Use the regadm set command to also configure HTTP proxy authentication settings, per your site's policy and requirements.

How to Configure HTTP Proxy Authentication Settings

Authenticate a specific user or account with My Oracle Support by specifying named credentials. 

Use the regadm auth command if you want to associate a registered system with a specific user or account.

How to Authenticate a User by Specifying Named Support Credentials

Tasks That Are Required Prior to Registration

The process of registering your system by using the regadm command includes gathering information and performing certain tasks prior to registration. The task flow is as follows:

  1. Configure HTTP proxy information, per site policy, if required.

  2. Configure HTTP proxy authentication information, per site policy, if required.

    For information about how to configure HTTP proxy settings, see Configuring Auto Registration Properties.

  3. Select a registration method.

    You can register in one of two ways, by specifying named support credentials or anonymously:

Displaying the Current Auto Registration Configuration

To display the currently authenticated user name and network connectivity information, use the regadm list command, as follows:


# regadm list

If you need to reset all of the property settings for a configuration, use the regadm clear command. For information, see How to Clear the Current Auto Registration Configuration.

Following are a few examples of various types of Auto Registration configurations.

Example 17–1 Authenticated User (No Proxy)


# regadm list
        My Oracle Support username      user@example.com
        HTTP Proxy                      <not configured>
        HTTP proxy port                 <not configured>
        HTTP proxy user                 <not configured>
        HTTP proxy password             <not configured>
Example 17–2 Authenticated User (Open Proxy With No Authentication)


# regadm list
        My Oracle Support username      user@example.com
        HTTP Proxy                      webproxy.example.com
        HTTP proxy port                 8080
        HTTP proxy user                 <not configured>
        HTTP proxy password             <not configured>
Example 17–3 Authenticated User (Proxy That Requires Authentication)


# regadm list
        My Oracle Support username      user@example.com
        HTTP Proxy                      webproxy.example.com
        HTTP proxy port                 8080
        HTTP proxy user                 webuser
        HTTP proxy password             ******

ProcedureHow to Clear the Current Auto Registration Configuration

Clearing the current configuration sets all of the Auto Registration properties to their default settings. This operation essentially has the same effect as a factory reset.

  1. Become superuser or assume an equivalent role.

  2. List the current Auto Registration configuration.


    # regadm list

  3. Clear the current Auto Registration configuration.


    # regadm clear

  4. Verify that the current configuration was cleared.


    # regadm list

    The output now displays the default settings for all property values. The default property values are not configured.

Example 17–4 Clearing the Current Auto Registration Configuration

In the following example, the regadm clear command is used to clear the property values of the current Auto Registration configuration.


# regadm list
        My Oracle Support username      user@example.com
        HTTP Proxy                      webproxy.example.com
        HTTP proxy port                 8080
        HTTP proxy user                 webuser
        HTTP proxy password             ******
# regadm clear
# regadm list
        My Oracle Support username      <not configured>
        HTTP Proxy                      <not configured>
        HTTP proxy port                 <not configured>
        HTTP proxy user                 <not configured>
        HTTP proxy password             <not configured>

Configuring Auto Registration Properties

The following Auto Registration properties can be configured by using the regadm command:

Previously configured HTTP proxy and port settings can be changed or reset to a direct network connection by using the regadm clear command. For instructions, see How to Clear the Current Auto Registration Configuration.

ProcedureHow to Configure HTTP Proxy and Port Settings

If you previously registered your system by using a direct network connection, or if you are performing a new registration, you might need to configure HTTP proxy and port settings prior to registering your system.

  1. Become superuser or assume an equivalent role.

  2. Set the HTTP proxy.


    # regadm set -n http_proxy -v webproxy-host

    The web proxy might be an IP address, a non-fully-qualified host name, or a fully-qualified host name.

  3. Set the HTTP port.


    # regadm set -n http_port -v port-number

ProcedureHow to Configure HTTP Proxy Authentication Settings

If your site implements HTTP proxy authentication, you must also configure HTTP proxy authentication settings (user name and password). The password must be specified as a single line in a text file and then passed to the regadm command. The following procedure describes how to protect the password file while it is in use. This file should be removed immediately after running the regadm command.

The regadm command accepts a password file in two cases:

  1. Become superuser or assume an equivalent role.

  2. Set the HTTP proxy user name.


    # regadm set -n http_proxy_user -v webuser

    where webuser is the site-supplied value to use for authenticating a user with the HTTP proxy server.

  3. Create a temporary password file.


    # touch pwfile

  4. Secure permissions on the file.


    # chmod 600 pwfile

  5. Using a text editor, edit the temporary password file to insert a one-line entry that contains your password information.

  6. Set the HTTP password authentication information.


    # regadm set -n http_proxy_pw -v pwfile

    where pwfile is the password file that you created in Step 3.

  7. Remove the password file.


    # rm pwfile
Example 17–5 Configuring HTTP Proxy Authentication Settings

The following example shows how to configure the HTTP authentication properties for a site that requires an HTTP user name and password for authentication purposes.


# regadm set -n http_proxy_user -v webuser
# touch myhttppasswd
# chmod 600 myhttppasswd
# vi myhttppasswd
.
.
.

# regadm set -n http_proxy_pw -v myhttppasswd
# rm myhttppasswd
Example 17–6 Switching From an HTTP Proxy Network Configuration to a Direct Connection

To switch network connectivity to a direct connection, you must set all of the HTTP proxy settings to a null value (not configured), as shown in the following example:


# regadm set -n http_proxy ""
# regadm set -n http_proxy_port ""
# regadm set -n http_proxy_user ""
# regadm set -n http_proxy_pw ""
# regadm list
        My Oracle Support username      <not configured>
        HTTP Proxy                      <not configured>
        HTTP proxy port                 <not configured>
        HTTP proxy user                 <not configured>
        HTTP proxy password             <not configured>

Authenticating a User by Specifying Named Support Credentials

Before a system's products can be registered, the user or account must be authenticated by specifying valid My Oracle Support credentials or valid Sun Online account credentials. If no support credentials are provided, the system is registered with an anonymous My Oracle Support account. You can use the regadm command with the auth subcommand, either interactively or non-interactively, to authenticate yourself with the Oracle Product Registration System.

Note –

Authentication must take place prior to registering by using the regadm register command.

The regadm auth command is used with the -u and -p options, as follows:


# regadm auth -u username -p pwfile

The -u option specifies a valid user name. The -p option specifies a file that contains password information for the user account.

The password file is a single-line file that you create and then add the credentials that are to be passed to the regadm command. The contents of the password file are private. For security reasons, remove the file immediately after the information is passed to the regadm command and a successful authentication has occurred.

Note –

A successful authentication persists across reboots and only needs to be provided one time. You can authenticate before or during an installation, or after an installation by using the regadm auth command. The password is never stored on the system. Only an opaque token is maintained after a successful authentication.

ProcedureHow to Authenticate a User by Specifying Named Support Credentials

The regadm auth command can be used to authenticate a user with My Oracle Support, either interactively or non-interactively. The following procedure describes how to use the command non-interactively. The examples that follow show how to run the command in both modes.

  1. Become superuser or assume an equivalent role.

  2. Create a temporary password file:


    # touch pwfile

  3. Secure permissions on the file:


    # chmod 600 pwfile

  4. Using a text editor, edit the temporary password file that you just created. Insert a one-line entry that contains your password information.

  5. Authenticate with My Oracle Support by specifying your named support credentials:


    # regadm auth -u user@example.com -p pwfile

    where user@example.com is either the My Oracle Support or Sun Online account user name, and pwfile is the password file that you created in Step 2.

    A message indicating that the authentication succeeded or failed is displayed.

  6. Proceed as follows:

  7. Remove the temporary password file:


    # rm pwfile
Example 17–7 Authenticating a User With Named Support Credentials (Non-Interactive)


# touch mospwfile
# chmod 600 mospwfile
# vi mospwfile
.
.
.
# regadm auth -u jdoe@mycompany.com -p mospwfile
Authenticating "jdoe@mycompany.com" with My Oracle Support
Authentication sucessful

You can now register this system with My Oracle Support
via "regadm register"
# rm mospwfile
Example 17–8 Authenticating a User With Named Support Credentials (Interactive)


# regadm auth
Enter your My Oracle Support username: jdoe@mycompany.com
Enter password:
Enter password again:
Authenticating "jdoe@mycompany.com" with My Oracle Support
Authentication successful

You can now register this system with My Oracle Support
via "regadm register"

Registering Your System by Using the regadm Command

Task 

Instructions 

For Information 

1. (Optional) Perform a dry run of a product registration. 

Use the regadm register command with the -d option to display service tag information about products that are yet to be registered, prior to actually registering. The output of the command displays the data that will be transmitted to My Oracle Support during an actual registration.

How to Display Registration Information About Products Not Yet Registered

2. Perform a product registration. 

Use the regadm register command to explicitly register your system, independent of an installation or upgrade.

How to Register Your System by Using the regadm Command

ProcedureHow to Display Registration Information About Products Not Yet Registered

Using the dry run function of the regadm register command enables you to display service tag information about products that are not yet registered. This function can be useful for system administrators who want to know what information will be sent to My Oracle Support prior to actually registering. Service tags enable automatic discovery of the products that are installed on your system. When you use the register -d command option, the service tag data that is to be transmitted to the Oracle Product Registration System is merely displayed.

Note –

To use the dry run command option you must be on a system that has network connectivity.

  1. Become superuser or assume an equivalent role.

  2. Type the regadm register command with the dry run command option, as follows:


    # regadm register -d

    The output of the command is displayed in XML file format.

Example 17–9 Displaying Registration Information About Products Not Yet Registered

The following example shows the output from running the regadm register command with the -d option. For brevity, the command output has been truncated.


# regadm register -d
Registering with My Oracle Support using username user@example.com
<?xml version="1.0"?>
<st1:request>
	<agent>
	<agent_urn>urn:st:5eabd994-12d0-6c6c-bf6e-a2cca89a0287</agent_urn>
	<agent_version>1.1.5.</agent_version>
	<registry_version>1.1.5</registry_version>
	<system_info>
		<system>SunOS</system>
		<host>hs-t1000-1</host>
		<release>5.10</release>
		<architecture>sparc</architecture>
		<platform>SUNW,Sun-Fire-T1000::Generic_141444-09</platform>
		.
		.
		.
	<system_info>
	</agent>
</st1:request>

<?xml version="1.0"?>
<st1:request>
	<service_tag>
		<instance_urn>urn:st:fd96de223-e190-6501-ff8d-dd76f1b708f5</instance_urn>
		<product_name>Solaris 10 Operating System</product_name>
.
.
.

ProcedureHow to Register Your System by Using the regadm Command

The regadm register command is used to register each product in the Service Tag Registry with My Oracle Support. Registration is accomplished by using the current authentication credentials. If no credentials are provided, the registration is performed anonymously by using an anonymous My Oracle Support account.

Before You Begin

Be sure to check Tasks That Are Required Prior to Registration for prerequisite instructions.

Consider also the following information:

  1. Become superuser or assume an equivalent role.

  2. List the current Auto Registration configuration.


    # regadm list

    If the output of the regadm list command does not display any configured Auto Registration properties (user name), the registration will be anonymous. Otherwise, the registration is associated with the user name that is displayed. If you are registering your system anonymously, but you prefer to provide support credentials, see How to Authenticate a User by Specifying Named Support Credentials before proceeding.

    If the output of the regadm list command does not display any HTTP proxy or port information, the registration will be performed by using a direct network connection. Otherwise, the existing HTTP property settings are used. If you need to reconfigure Auto Registration properties for network connectivity, see How to Configure HTTP Proxy and Port Settings before proceeding.

  3. Register your system.


    # regadm register
    Note –

    The output of the regadm register command varies, depending on how the Auto Registration feature is configured on your system.

Example 17–10 Registering Your System Anonymously

The following example shows an anonymous registration on a system where no named support credentials were configured prior to registration. The registration also uses a direct network connection.


# regadm list
        My Oracle Support username      <not configured>
        HTTP Proxy                      <not configured>
        HTTP proxy port                 <not configured>
        HTTP proxy user                 <not configured>
        HTTP proxy password             <not configured>
# regadm register
Registered Solaris 10 Operating System
Registration Successful
Example 17–11 Registering Your System by Specifying Named Support Credentials

The following example shows a registration on a system where support credentials and HTTP proxy and port information were configured prior to registration.


# regadm list
        My Oracle Support username      user@example.com
        HTTP Proxy                      webproxy.example.com
        HTTP proxy port                 8080
        HTTP proxy user                 <not configured>
        HTTP proxy password             <not configured>
# regadm register
Registering with My Oracle Support using username user@example.com
Registered Solaris 10 Operating System
Registration successful

Obtaining Information About Currently Registered Products

To obtain service tag information for products that are currently registered with the Auto Registration feature, go to https://inventory.sun.com/inventory/data.jsp.

To access service tag information for your registered products, you must first log in with either your My Oracle Support account credentials or your Sun Online account credentials.

Note –

Be aware that the inventory web site provides information about discovery and registration methods that are not associated with the new Auto Registration feature. These other registration methods are used on a voluntary basis and registration is not mandatory. If you have installed Oracle Solaris 10 9/10, Auto Registration occurs upon the first reboot after an installation or upgrade.

For general information about how your system's assets are managed with service tags, go to http://wikis.sun.com/display/ServiceTag/Home.

Troubleshooting Auto Registration Issues

The more common errors that you might encounter while attempting to authenticate or register your system can be resolved by following basic troubleshooting strategies. The following are issues that you might need to troubleshoot when using the regadm command:

Authentication Failed

If you attempt to authenticate yourself with My Oracle Support by using the regadm auth command, and the authentication fails, the following message is displayed after you type your user name and password:


Authentication failed

To troubleshoot this issue, verify that you are using the correct account credentials (My Oracle Support user name and password, or Sun Online account user name and password). To verify your account settings, go to https://reg.sun.com/accounthelp.

For answers to common questions and information about how to gain initial access to My Oracle Support, go to http://www.oracle.com/us/support/044753.html#SS6.

Cannot Send HTTP Proxy Password

For security reasons, the HTTP proxy password must be located in a file rather than specified on the command line. If the password has not been specified in a file, the regadm command cannot locate the password. Consequently, the following message is displayed when you attempt to set your password:


# regadm set -n http_proxy_pw -v secret1
Cannot find file 'secret1'

For instructions on setting the HTTP proxy password, see How to Configure HTTP Proxy Authentication Settings.

HTTP Communications Error

If a problem exists with your HTTP configuration, the following error message might be displayed:


HTTP Communications error with Oracle Support Center

Please check your HTTP settings and retry your request.

There can be one or more reasons that this error message is displayed. To troubleshoot the problem, follow these steps:

  1. Verify that your HTTP configuration is correct by typing the following command:


    # regadm list

  2. If your configuration is correct, check the following information:

    • Does your system have access to the public Internet, either directly or through an HTTP proxy? If not, you cannot use the regadm command to administer the Auto Registration feature.

    • Is an HTTP proxy required at your site? If so, ensure that the HTTP proxy host and port have been configured correctly. For instructions, see How to Configure HTTP Proxy and Port Settings.

    • Is authenticated proxy access required at your site? If so, verify that the proxy user name and password have been configured and typed correctly. For instructions, see How to Configure HTTP Proxy Authentication Settings.

  3. Ensure that your HTTP proxy host setting can be resolved to a valid web proxy host that is up and running and has a name that is resolvable.

    For example, if your configured HTTP proxy host is webproxy.example.com, it should be both resolvable and able to respond to a request from the ping utility, as follows:


    # getent hosts webproxy.example.com
192.168.1.1 webproxy.example.com
# ping webproxy.example.com
webproxy.example.com is alive

    For more information, see the getent(1M) and ping(1M) man pages.

  4. If the previous troubleshooting steps do not work, verify your settings with your site administrator.