Version: Release 23.3

Using CIFS, SMB, WinRM, and Telnet

This topic provides information about Using CIFS, SMB, WinRM, and Telnet in Release.

Remoting functionality for Deploy and Release supports the CIFS and SMB protocols for file manipulation and WinRM and Telnet for process execution. For more information, see Deploy Remoting plugin and Release Remoting plugin.

Microsoft Windows' built-in file sharing capabilities are based on CIFS and are available and enabled by default. You should not need to install new software on a target CIFS or SMB host. You may need to enable and configure some services.

To connect to a remote host using CIFS or SMB, ensure the host is reachable on port 445.

WinRM is available on Windows Server 2008 and later. The Remoting plugin supports basic authentication for local accounts and Kerberos authentication for domain accounts. Overthere has a built-in WinRM library that can be used from all operating systems by setting the connection type on a CIFS host (CI type overthere.CifsHost) to WINRM_INTERNAL. When connecting from a host that runs Windows, or when using a winrs proxy that runs Windows, the native WinRM capabilities of Windows (the winrs command) can be used by setting the connection type to WINRM_NATIVE.

A Telnet Server is available on all Windows Server versions.

Set up WinRM

To use the WINRM_INTERNAL or the WINRM_NATIVE connection type, set up Microsoft Windows Remote Management on the remote host.

Microsoft documentation

For details on WinRM and using the quickconfig command, see the following:

Prerequisites

Depending on your system, select one of the following options:

If the remote host is running Windows Server 2003 SP1 or SP2, or Windows XP SP2, install the WS-Management v.1.1 package.
If the remote host is running Windows Server 2003 R2, go to Control Panel > Add/Remove System Components, and add WinRM under Management and Monitoring Tools. Then, install the WS-Management v.1.1 package to upgrade the WinRM installation.
If the remote host is running Windows Vista or Windows 7, the Windows Remote Management (WS-Management) service is not started by default. Start the service and change its startup type to Automatic (Delayed Start) before proceeding.

Run the quick configuration

On the remote host, open PowerShell or a command prompt using the Run as Administrator option.

note

The Windows Firewall must be running to run this command. For more information, see Microsoft Knowledge Base article #2004640.

Configure options

Enable basic authentication

Optionally, enable basic authentication. By default, basic authentication is disabled in WinRM. Enable it if you are going to use local accounts to access the remote host:

winrm set winrm/config/service/Auth @{Basic="true"}

Enable or disable Kerberos authentication

By default, Kerberos authentication is enabled in WinRM. You can optionally enable or disable Kerberos authentication.

If you want to use Kerberos authentication, see Set up Kerberos for WinRM.

If you are not going to use domain accounts to access the remote host, disable Kerberos:

winrm set winrm/config/service/Auth @{Kerberos="false"}

note

Do not disable Negotiate authentication, as the winrm command itself uses it to configure the WinRM subsystem.

Configure SOAP handling

Optionally, configure WinRM to allow unencrypted SOAP messages. This step is only required for WINRM_INTERNAL or when the property winrsUnencrypted is set to true.

To configure WinRM to allow unencrypted SOAP messages:

winrm set winrm/config/service @{AllowUnencrypted="true"}

Configure connections from trusted hosts

Configure WinRM to accept connections from trusted hosts:

winrm set winrm/config/client @{TrustedHosts="*"}

note

This is not always required and the command as given will accept connections from all hosts. This command can be refined by specifying hostnames. For example:

winrm set winrm/config/client @{TrustedHosts="host1,host2..."}

HTTPS configuration

To use the WINRM_INTERNAL or WINRM_NATIVE connection type with HTTPS, with winrmEnableHttps set to true, follow these steps:

Optionally, create a self-signed certificate for the remote host by installing selfssl.exe from the IIS 6 resource kit and running the command below or by following the instructions in this blog post by Hans Olav.

C:\Program Files\IIS Resources\SelfSSL>selfssl.exe /T /N:cn=HOSTNAME /V:3650
Microsoft (R) SelfSSL Version 1.0
Copyright (C) 2003 Microsoft Corporation. All rights reserved.

Do you want to replace the SSL settings for site 1 (Y/N)?Y
The self signed certificate was successfully assigned to site 1.

Open a PowerShell window and enter the following command to find the thumbprint for the certificate for the remote host:

	PS C:\Windows\system32> Get-childItem cert:\LocalMachine\Root\ | Select-String -pattern HOSTNAME

	[Subject]
	  CN=HOSTNAME

	[Issuer]
	  CN=HOSTNAME

	[Serial Number]
	  527E7AF9142D96AD49A10469A264E766

	[Not Before]
	  5/23/2011 10:23:33 AM

	[Not After]
	  5/20/2021 10:23:33 AM

	[Thumbprint]
	  5C36B638BC31F505EF7F693D9A60C01551DD486F

Create an HTTPS WinRM listener for the remote host with the thumbprint you've just found:

	winrm create winrm/config/Listener?Address=*+Transport=HTTPS @{Hostname="HOSTNAME"; CertificateThumbprint="THUMBPRINT"}

If you are using the WINRM_INTERNAL connection type, add the self-signed certificate to the JVM trusted keystore.

Domain accounts

For the WINRM_INTERNAL connection type, domain accounts must be specified using the new-style domain syntax. For example, USER@FULL.DOMAIN. For the WINRM_NATIVE connection type, domain accounts can be specified using either the new-style (USER@FULL.DOMAIN) or old-style (DOMAIN\USER) domain syntax. For both connection types, local accounts must be specified without an at sign (@) or a backslash (\).

Password limitations

Due to a limitation of the winrs command, passwords containing a single quotation mark (') or a double quotation mark (") cannot be used with the WINRM_NATIVE connection type.

Set up Kerberos for WinRM

If you want to use Microsoft Windows domain accounts to access remote hosts with the WINRM_INTERNAL connection type, you must configure Kerberos. Using Kerberos authentication requires that you follow the Kerberos Requirements for Java on the host that runs the Deploy or Release server.

Dending on your system, select
- Unix-based system create a file called krb5.conf.
- Microsoft Windows system create a file called krb5.ini

At a minimum, add the following content to the file you created:

[libdefaults]
    default_realm = EXAMPLE.COM

[realms]
    EXAMPLE.COM = {
        kdc = KDC.EXAMPLE.COM
    }

Replace the values with the name of your domain/realm and the hostname of your domain controller. You can add multiple entries to allow the Deploy server host to connect to multiple domains.
Choose where you want to store your file:
- Store the file in the default location for your operating system. The default locations are:
  - Linux: /etc/krb5.conf
  - Solaris: /etc/krb5/krb5.conf
  - Microsoft Windows: C:\Windows\krb5.ini
    Or
- Store the file in another location. If you want to store the file in a different location, add the following line to XL_DEPLOY_SERVER_HOME/conf/xld-wrapper.conf. Replace the path with the file location:
```
wrapper.java.additional.5=-Djava.security.krb5.conf=/path/to/krb5.conf
```

For more information on the krb5.conf format, see the Kerberos V5 System Administrator's Guide at MIT.

important

The value of AllowUnencrypted="true" is required for WINRM_INTERNAL. Otherwise, you must install deploy on a windows server to use WIMRM_NATIVE. However, there are a few scenarios where this is not necessary. Eg: Kerberos authentication is already encrypted and using https that would encrypt the soap messages.

Set up Kerberos for Deploy satellite

If you are using the Deploy satellite module with Kerberos, follow the instructions described in Set up Kerberos for WinRM to create a krb5.conf (Unix) or krb5.ini (Microsoft Windows) file on the satellite. For more information, see Getting started with the satellite module

If you want to store the file in the default location for the satellite's operating system, no additional changes are required.

If you want to store the file in a different location, add the following line to the run.sh or run.cmd script on the satellite and replacing the path with the file location:

-Djava.security.krb5.conf=/path/to/krb5.conf

For more information on configuring satellites, see Install and configure a satellite server.

Generate the Kerberos configuration file

It can be difficult to determine the right Microsoft Windows domain name and the hostnames of all domain controllers. You can generate the configuration by creating a PowerShell script called generate-krb5-conf.ps1 on a Windows machine in the target domain with the following contents:

$domain = [System.DirectoryServices.ActiveDirectory.Domain]::GetComputerDomain()

Write-Output "[libdefaults]"
Write-Output "    default_realm = $($domain.Name.ToUpper())"
Write-Output ""
Write-Output "[realms]"
Write-Output "    $($domain.Name.ToUpper()) = {"
foreach ($kdc in $domain.DomainControllers) {
  Write-Output "        kdc = $($kdc.Name)"
}
Write-Output "    }"

Now, run the script with the following command:

powershell -f generate-krb5-conf.ps1

Configuration for the remote host

By default, Deploy or Release will request access to a Kerberos service principal name of the form WSMAN/HOST, for which an SPN should be configured automatically when you configure WinRM for a remote host.

If it was not configured correctly â€” for example, if you have overridden the default SPN for which a ticket is requested through the winrmKerberosAddPortToSpn or the winrmKerberosUseHttpSpn properties â€” you will need to configure the service principal names manually. This can be achieved by invoking the setspn command, as an Administrator, on any host in the domain, as follows:

setspn -s PROTOCOL/ADDRESS:PORT WINDOWS-HOST

Where:

PROTOCOL is WSMAN (default) or, if winrmKerberosUseHttpSpn has been set to "true", HTTP.
ADDRESS used to connect to the remote host
PORT (optional) port used to connect to the remote host. This is usually 5985 or 5986 and is only necessary if winrmKerberosAddPortToSpn has been set to "true".
WINDOWS-HOST is the short Windows hostname of the remote host.

Enable multi-hop support (CredSSP) for WinRM

To enable multi-hop support, which is also known as CredSSP, for WinRM when using the WINRM_NATIVE connection type, follow the steps below.

note

multi-hop support is not supported by the WINRM_INTERNAL connection type.

Configure the server

On the Deploy, Deploy satellite, and/or Release server:

Execute the following command:

winrm set winrm/config/client/auth @{CredSSP="true"}

Open the Group Policy Editor (gpedit.msc).
Go to Computer Configuration > Administrative Templates > System > Credentials Delegation.
Edit Allow Delegating Fresh Credentials.
Select Enabled.
Add the SPNs for target servers to the list. For example, WSMAN/hostname.domain.

note

Commands like WSMAN/* are permitted.

Click Apply.

If the server is not in the same Windows domain as at least one of the target machines, you must also:

Edit Allow Delegating Fresh Credentials with NTLM-only Server Authentication.
Select Enabled.
Add the SPNs for target servers to the list. For example, WSMAN/hostname.domain.
Click Apply.

Configure each target machine

On each target machine, execute the following command:

winrm set winrm/config/service/auth @{CredSSP="true"}

Configure the host CIs

For each target machine, set the Allow credential delegation (winrsAllowDelegate) property on the host configuration item (overthere.Host), in Deploy or Release, to "true".

Useful WinRM commands

These commands are useful when you are using WinRM to execute commands and manipulate files on a remote host.

Quickly configure WinRM with HTTPS:
```
winrm quickconfig -transport:https
```

View the complete WinRM configuration:
```
winrm get winrm/config
```

View the listeners that have been configured:
```
winrm enumerate winrm/config/listener
```

Create an HTTP listener:

winrm create winrm/config/listener?Address=*+Transport=HTTP` (also done by `winrm quickconfig`)

Allow all hosts to connect to the WinRM listener:

winrm set winrm/config/client @{TrustedHosts="*"}

Allow a fixed set of hosts to connect to the WinRM listener:

winrm set winrm/config/client @{TrustedHosts="host1,host2..."}

List all service principal names configured for the domain when using Kerberos:
```
setspn -Q */*
```

List all service principal names configured for a specific host in the domain when using Kerberos:
```
setspn -L _WINDOWS-HOST_
```

Set up Telnet

To use the TELNET connection type, enable and configure the Telnet Server on the remote host:

Optionally, if the Telnet Server is not already installed on the remote host, add it using the Add Features Wizard in the Server Manager console.
Optionally, if the remote host is running Windows Server 2003 SP1 or an x64-based version of Windows Server 2003, install the Telnet server as described on the Microsoft Support site.
Enable the Telnet Server Service on the remote host as described on the Microsoft Technet site.
After you have started the Telnet Server, open a command prompt as the Administrator user on the remote host, and enter the command tlntadmn config mode=stream to enable stream mode.

When the Telnet server is enabled, any user that is in the Administrators group or that is in the TelnetClients group, and has the Allow logon locally privilege, can log in using Telnet. For information on how to grant a user the right to logon locally, see Windows Server 2008 R2.

Domain accounts

For the TELNET connection type, domain accounts must be specified using the old-style domain syntax, e.g DOMAIN\USER.

Using administrative shares with CIFS

By default, Deploy and Release will access administrative shares on the remote host. These shares are only accessible for users that have administrator privileges on the remote host.

You can use Windows-style paths such as C:\Program Files\IBM\WebSphere\AppServer, these will be translated to SMB URLs that use administrative shares. For example, if you provide the path C:\IBM\WebSphere\profiles\Dmgr01 on a CIFS host (overthere.CifsHost) called windows1, it will be translated to the SMB path \\windows1\C$\IBM\WebSphere\profiles\Dmgr01, which is equivalent to the JCIFS URL smb://windows1/C$/IBM/WebSphere/profiles/Dmgr01. An administrative share such as C$ can only be accessed by users with administrator privileges.

If you want to access the remote host with an account that does not have administrator privileges, you can specify other shares in the Windows path to Windows share mappings (pathShareMapping) property on the CIFS host (overthere.CifsHost). For example, if you map the WebSphere share to C:\IBM\WebSphere, it will be translated to the SMB path C:\IBM\WebSphere\profiles\Dmgr01 on host windows1 to \\windows1\WebSphere\profiles\Dmgr01, instead of \\windows1\C$\IBM\WebSphere\profiles\Dmgr01.

If you are using a plugin that will copy a file to a temporary directory, such as the Deploy File plugin or Generic plugin, you must either:

Add the directory to the mapping. Or
Set the copyDirectlyToTargetPath hidden property on the CIFS host to "true". In this case, the file will be copied directory to the target directory.

note

The user identified by the username (username) property on the CIFS host must have access to the shares that you specify, as well as to the underlying directories and files.

Set up WinRM​

Microsoft documentation​

Prerequisites​

Run the quick configuration​

Configure options​

Enable basic authentication​

Enable or disable Kerberos authentication​

Configure SOAP handling​

Configure connections from trusted hosts​

HTTPS configuration​

Domain accounts​

Password limitations​

Set up Kerberos for WinRM​

Set up Kerberos for Deploy satellite​

Generate the Kerberos configuration file​

Configuration for the remote host​

Enable multi-hop support (CredSSP) for WinRM​

Configure the server​

Configure each target machine​

Configure the host CIs​

Useful WinRM commands​

Set up Telnet​

Domain accounts​

Using administrative shares with CIFS​

Set up WinRM

Microsoft documentation

Prerequisites

Run the quick configuration

Configure options

Enable basic authentication

Enable or disable Kerberos authentication

Configure SOAP handling

Configure connections from trusted hosts

HTTPS configuration

Domain accounts

Password limitations

Set up Kerberos for WinRM

Set up Kerberos for Deploy satellite

Generate the Kerberos configuration file

Configuration for the remote host

Enable multi-hop support (CredSSP) for WinRM

Configure the server

Configure each target machine

Configure the host CIs

Useful WinRM commands

Set up Telnet

Domain accounts

Using administrative shares with CIFS