2.5.9 setup-local-dcom

Sets up DCOM on a host.

Synopsis

asadmin [asadmin-options] setup-local-dcom [--help]
    [--unsetup={false|true}] [--verbose={false|true}]
    [--force={false|true}]

Storage location

Application Server installation directory/javaee/glassfish/bin

Function

The setup-local-dcom subcommand sets up the Distributed Component Object Model (DCOM) remote protocol on the host where the subcommand is run. The DCOM remote protocol is available only on Windows systems.

This subcommand must be run by the operating-system-level administrator user on the host where DCOM is set. Before running this command, ensure that DCOM settings in the Windows operating system are set as described in the documents of the GlassFish Server Open Source Edition.

Setting up DCOM on a host ensures that you can run the scripts on the host from a remote host. To run scripts on the host from a remote host, the Windows user must be allowed full control over some of the Windows registry keys.

In some versions of Windows, only the user NT SERVICE\TrustedInstaller has full control over these Windows registry keys. If the version of Windows on a host is configured using this method, then this subcommand modifies these keys to allow full control over them for the respective Windows user.

Important note: This subcommand may modify some keys in the Windows registry. Before running this command, back up the Windows registry.

By default, the subcommand prompts you to confirm whether to update the Windows registry. To run the subcommand without being prompted, set the --force option to true.

After updating the Windows registry using this subcommand, you must restart Remote Registry service.

This subcommand is supported in the local mode only.

When this subcommand is run, the registry is updated to make the following DCOM applications available. In addition, if you specify the --unsetup option, the registry is updated to make the following DCOM applications unavailable.

Windows Script Host Shell Object (WSH)

AppID={72C24DD5-D70A-438B-8A42-98424B88AFB8}
WBEM Scripting Locator (WMI)

AppID={76A64158-CB41-11D1-8B02-00600806D9B6}

When this subcommand is run, the registry setting is updated as follows:

When you set up:

In the registry of the host running this subcommand, to change the permission settings of the keys "HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\" and "HKEY_CLASSES_ROOT\CLSID\" as follows:

Key: {72C24DD5-D70A-438B-8A42-98424B88AFB8}

Key: {76A64158-CB41-11D1-8B02-00600806D9B6}

*Change the permission settings

Owner: Change as follows:

- Administrators

Permission entries: Change the following entries and permission settings accordingly:

- Administrators: Special permissions (Full Control or equivalent)

- Everyone: Read permissions

In the registry of the host running this subcommand, for the "HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\" and "HKEY_CLASSES_ROOT\CLSID\" keys, the following values are registered:

Key: {72C24DD5-D70A-438B-8A42-98424B88AFB8}

Value name: AppID

Value data: {72C24DD5-D70A-438B-8A42-98424B88AFB8}

Key: {76A64158-CB41-11D1-8B02-00600806D9B6}

Value name: AppID

Value data: {76A64158-CB41-11D1-8B02-00600806D9B6}

The registry of the host running this sub-command, for the "HKEY_LOCAL_MACHINE\SOFTWARE\Classes\AppID\" and "HKEY_CLASSES_ROOT\AppID\" keys, the following key and value are registered:

Key: {72C24DD5-D70A-438B-8A42-98424B88AFB8}

Value name: DllSurrogate

Value data: N/A

Key: {76A64158-CB41-11D1-8B02-00600806D9B6}

Value name: DllSurrogate

Value data: N/A

The following value must be changed, when the "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\RemoteRegistry" key exists in registry on the host where the subcommand is run:

Value name: DisableIdleStop

Value data: 1
When you remove:

In the registry of the host running this subcommand, for the "KEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\" and "HKEY_CLASSES_ROOT\CLSID\" keys, the following keys and values are deleted:

Key: {72C24DD5-D70A-438B-8A42-98424B88AFB8}

Value name: AppID

Key: {76A64158-CB41-11D1-8B02-00600806D9B6}

Value name: AppID

In the registry of the host running this subcommand, for the keys "HKEY_LOCAL_MACHINE\SOFTWARE\Classes\AppID\" and "HKEY_CLASSES_ROOT\AppID\", the following keys are deleted (The registered value to the key will also be deleted):

Key: {72C24DD5-D70A-438B-8A42-98424B88AFB8}

Key: {76A64158-CB41-11D1-8B02-00600806D9B6}

The following value must be changed, when the "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\RemoteRegistry" key exists in registry on the host where the subcommand is run:

Value name: DisableIdleStop

Value data: 0

Execution permission

OS-level administrator user

Arguments

--help | -?

Displays the help text for the subcommand.

--force={false|true}

Specifies whether the subcommand prompts you to confirm whether to update the Windows registry.

Type: Boolean

The following values can be specified:

false

Prompts you to confirm whether to update the Windows registry. This is the default value.
true

Updates the registry forcibly without prompting you for a confirmation.

Default value: false

--verbose={false|true}

Specifies whether the subcommand displays information about the operations that are performed to set up DCOM on the host.

Type: Boolean

The following values can be specified:

false

Information about the operations that are performed to set up DCOM is not displayed. This is the default value.
true

Displays information about the operations that are performed to set up DCOM on the host.

Default value: false

--unsetup={false|true}

Specifies whether to remove DCOM on the host.

Type: Boolean

The following values can be specified:

false

Set up DCOM on the host. This is the default value.
true

Remove DCOM on the host.

Default value: false

Examples

The following example sets up DCOM on the host where the subcommand is run:

asadmin setup-local-dcom
Caution: This command might modify the permissions of some keys in the Windows
registry.
Before running this command, back up the Windows registry.
The modification allows the Windows user full control over these keys.
Are you sure that you want to edit the Windows registry? If so, type yes in full:
yes
Command setup-local-dcom executed successfully.

Exit Status

Exit Status	Explanation
`0`	subcommand executed successfully.
`1`	error in executing the subcommand.

Notes

When you run this subcommand with the value as true for the --unsetup option, the following applications will be deleted from the DCOM configuration.

If other programs, which use DCOM, use the following applications, then you must not remove the DCOM settings by using the --unsetup=true option.
- Windows Script Host Shell Object (WSH)
  
  AppID={72C24DD5-D70A-438B-8A42-98424B88AFB8}
- WBEM Scripting Locator (WMI)
  
  AppID={76A64158-CB41-11D1-8B02-00600806D9B6}
When the --unsetup option is specified as true on the systems which run the operating systems Windows 8 (or later versions) or Windows Server 2012 (or later versions), this subcommand restores the IdleStop feature of the Remote Registry Service to the default setting of the respective operating system. By default, the IdleStop feature is enabled. To permanently disable the IdleStop feature, do one of the following:
- Do not specify --unsetup=true when this subcommand is run.
- If the subcommand is run when --unsetup=true is specified, then change the value of the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\RemoteRegistry\DisableIdleStop registry key to 1.
If the registry key does not exist , then this subcommand does not add the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\RemoteRegistry registry key to set the value.

To Page Top