Remote endpoint connection

Authenticate with passwords

This method authenticate via SSH with a username and password. Ansible provides several useful options that can be used for SSH authentication with passwords:

• -u <user> set the connection user.

• -k prompt for the user's SSH password to the remote endpoint.

• -b execute task and operations with a privilege user.

• -K prompt for the sudo password.

You can use the above arguments as follows:

# ansible -m setup all -u foo -k -b -K

This command sets the connection user as foo. Also, it requests the connection user password and privileged user password.

Authenticate with SSH key-pairing

You can set up an SSH key-pair to provide a passwordless authentication mechanism. Perform the following steps to set up SSH key-pairing between the Ansible control server and the managed endpoint.

1. Generate the SSH authentication key pair for the root user of the Ansible control server using the ssh-keygen tool.

   1. Switch to root and navigate to the $HOME directory of the Ansible server:

      $ sudo su
      # cd ~
      

   2. Generate an authentication key pair for SSH:

      # ssh-keygen
      

      Note

      • To improve security on this setup, please ensure you provide a passphrase for this key.

      • Using ssh-agent, we can avoid repeatedly asking for the key password on every Ansible deployment. Ssh-agent will cache the key to be used in further actions, until you log out.

   3. Verify the permissions of the generated keys:

      # ls -la ~/.ssh
      

      id_rsa must have restrictive permissions (600 or "-rw-------").

      drwx------. 2 root root   57 Mar 18 10:06 .
      dr-xr-x---. 5 root root  210 Mar 18 08:44 ..
      -rw-------. 1 root root 1675 Mar 18 12:34 id_rsa
      -rw-r--r--. 1 root root  408 Mar 18 12:34 id_rsa.pub
      -rw-r--r--. 1 root root  175 Mar 18 10:14 known_hosts
      

      The /root/.ssh/ directory must have its permissions set to 700 (drwx------). The permissions can be set using the command below:

      # chmod 700 ~/.ssh/
      

2. Follow the steps below to prepare the remote endpoint to receive the Ansible server public key.

   1. Install OpenSSH server if it is not present.

      CentOS/RHEL/FedoraUbuntu/Debian

      # yum install openssh-server
      

   2. Start the SSH service.

      SystemdSysV Init

      • CentOS / RHEL / Fedora:

        # systemctl start sshd
        

      • Ubuntu/Debian:

        # systemctl start ssh
        

   3. Navigate to the $HOME directory of the remote endpoint, create the .ssh directory, and assign the appropriate permissions to it:

      $ cd ~
      $ mkdir .ssh
      $ chmod 700 .ssh/
      

   4. Create the authorized_keys file in the .ssh/ directory with the appropriate permission if it is not there by default, otherwise the public key authentication will not work properly:

      $ touch .ssh/authorized_keys
      $ chmod 644 .ssh/authorized_keys
      

3. Follow the steps below to add the public key (id_rsa.pub) of the Ansible server to the ~/.ssh/authorized_keys file in the $HOME directory of the remote endpoint using SSH.

   1. Run the command below from the Ansible server:

      # cat ~/.ssh/id_rsa.pub | ssh <REMOTE_ENDPOINT_USERNAME>@<REMOTE_ENDPOINT_IP_ADDRESS> "cat >> ~/.ssh/authorized_keys"
      

   2. Verify that the key is stored on the remote endpoint:

      # cat ~/.ssh/authorized_keys
      

4. Confirm SSH configuration allows public key authentication. Edit /etc/ssh/sshd_config on the remote endpoint and ensure the following settings are uncommented:

   PubkeyAuthentication yes
   AuthorizedKeysFile .ssh/authorized_keys
   

5. Restart the SSH service:

   SystemdSysV Init

   • CentOS / RHEL / Fedora:

     # systemctl start sshd
     

   • Ubuntu/Debian:

     # systemctl start ssh
     

6. Test the connection from the Ansible server:

   # ssh <REMOTE_ENDPOINT_USERNAME>@<REMOTE_ENDPOINT_IP_ADDRESS>
   

   You should connect without being prompted for a password.

Requirements

The following minimum requirements should be met to use Ansible on Windows endpoints:

• Supported Windows versions: Windows 7, 8.1, 10, Server 2008 (including R2), 2012 (including R2), 2016, 2019.

• PowerShell 3.0 or later.

• .NET Framework 4.0 or later.

• A Windows Remote Management (WinRM) listener configured and running. Ansible communicates with Windows endpoints over WinRM HTTPS (port 5986).

Configuring WinRM on Windows endpoints

Run the following commands in PowerShell as Administrator on the Windows endpoint.

1. Verify the existing WinRM listeners. By default, only the HTTP listener (port 5985) is enabled:

   winrm enumerate winrm/config/Listener
   

   Listener
       Address = *
       Transport = HTTP
       Port = 5985
       Hostname
       Enabled = true
       URLPrefix = wsman
       CertificateThumbprint
       ListeningOn = 127.0.0.1, 172.31.78.21, ::1, fe80::dbdf:890c:7f17:b1f1%6
   

2. Obtain the hostname of the Windows endpoint:

   Write-Output $env:COMPUTERNAME
   

   Windows11
   

3. Create a self-signed certificate for the endpoint hostname:

   New-SelfSignedCertificate -DnsName "<DNS_NAME>" -CertStoreLocation Cert:\LocalMachine\My
   

   Replace <DNS_NAME> with the hostname obtained in the previous step, and note the certificate thumbprint returned.

   PSParentPath: Microsoft.PowerShell.Security\Certificate::LocalMachine\My
   
   Thumbprint                                Subject
   ----------                                -------
   DD8FA81230445C6AFB90B253BF996345E0ADF6FC  CN=EC2AMAZ-JNOKRGC
   

4. Create an HTTPS WinRM listener using the certificate thumbprint:

   winrm create winrm/config/Listener?Address=*+Transport=HTTPS '@{Hostname="<DNS_NAME>"; CertificateThumbprint="<CERTIFICATE_THUMBPRINT>"}'
   

   Replace:

   • <DNS_NAME> with the Windows endpoint hostname obtained above.

   • <CERTIFICATE_THUMBPRINT> with the thumbprint of the certificate.

5. Open port 5986 on the Windows firewall to allow WinRM HTTPS traffic:

   netsh advfirewall firewall add rule name="Windows Remote Management (HTTPS-In)" dir=in action=allow protocol=TCP localport=5986
   

6. Verify that the HTTPS listener is enabled:

   winrm enumerate winrm/config/Listener
   

   Listener
       Address = *
       Transport = HTTP
       Port = 5985
       Hostname
       Enabled = true
       URLPrefix = wsman
       CertificateThumbprint
       ListeningOn = 127.0.0.1, 172.31.78.21, ::1, fe80::dbdf:890c:7f17:b1f1%6
   
   Listener
       Address = *
       Transport = HTTPS
       Port = 5986
       Hostname = EC2AMAZ-JNOKRGC
       Enabled = true
       URLPrefix = wsman
       CertificateThumbprint = DD8FA81230445C6AFB90B253BF996345E0ADF6FC
       ListeningOn = 127.0.0.1, 172.31.78.21, ::1, fe80::dbdf:890c:7f17:b1f1%6
   

7. Enable Basic authentication if it is not enabled:

   Set-Item -Path WSMan:\localhost\Service\Auth\Basic -Value $true
   

   Note

   As an optional step, run the command below to remove the default HTTP listener to enforce secure communication:

   winrm delete winrm/config/Listener?Address=*+Transport=HTTP
   

   Basic authentication must be used only with HTTPS enabled. For production environments, we recommend more secure authentication methods such as Kerberos, NTLM or certificate-based authentication.

Linux endpoints

Perform the following steps using the ping module to confirm that the Ansible control server can connect to Linux endpoints over SSH:

1. Test the connection with the ping module:

   # ansible all -m ping
   

   The expected output is:

   linux_remote_endpoint_1 | SUCCESS => {
       "changed": false,
       "ping": "pong"
   }
   

Windows endpoints

Perform the following steps using the win_ping module to confirm that the Ansible control server can connect to Windows endpoints over WinRM:

1. Test the connection:

   ansible windows_remote_endpoints -m win_ping
   

   The expected output is:

   windows_remote_endpoint_1 | SUCCESS => {
       "changed": false,
       "ping": "pong"
   }