NETCONF over SSHv2

You can use the Network Configuration Protocol (NETCONF) over Secure Shell Version 2 (SSHv2) feature to perform network configurations via the Cisco command-line interface (CLI) over an encrypted transport. The NETCONF Network Manager, which is the NETCONF client, must use Secure Shell Version 2 (SSHv2) as the network transport to the NETCONF server. Multiple NETCONF clients can connect to the NETCONF server.

Finding Feature Information

Your software release may not support all the features documented in this module. For the latest caveats and feature information, see Bug Search Tool and the release notes for your platform and software release. To find information about the features documented in this module, and to see a list of the releases in which each feature is supported, see the feature information table at the end of this module.

Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/​go/​cfn. An account on Cisco.com is not required.

Prerequisites for NETCONF over SSHv2

  • NETCONF over SSHv2 requires that a vty line be available for each NETCONF session as specified in the netconf max-session command.

Restrictions for NETCONF over SSH

  • Network Configuration Protocol (NETCONF) Secure Shell Version 2 (SSHv2) supports a maximum of 16 concurrent sessions.

  • Only SSH version 2 is supported.

Information About NETCONF over SSHv2

NETCONF over SSHv2

To run the NETCONF over SSHv2 feature, the client (a Cisco device running Cisco software) establishes an SSH transport connection with the server (a NETCONF network manager). The following image shows a basic NETCONF over SSHv2 network configuration. The client and server exchange keys for security and password encryption. The user ID and password of the SSHv2 session running NETCONF are used for authorization and authentication purposes. The user privilege level is enforced and the client session may not have full access to the NETCONF operations if the privilege level is not high enough. If authentication, authorization, and accounting (AAA) is configured, the AAA service is used as if a user had established an SSH session directly to the device. Using the existing security configuration makes the transition to NETCONF almost seamless. Once the client has been successfully authenticated, the client invokes the SSH connection protocol and the SSH session is established. After the SSH session is established, the user or application invokes NETCONF as an SSH subsystem called “netconf.”

Figure 1. NETCONF over SSHv2

Secure Shell Version 2

SSHv2 runs on top of a reliable transport layer and provides strong authentication and encryption capabilities. SSHv2 provides a means to securely access and securely execute commands on another computer over a network.

NETCONF does not support SSH version 1. The configuration for the SSH Version 2 server is similar to the configuration for SSH version 1. Use the ip ssh version command to specify which version of SSH that you want to configure. If you do not configure this command, SSH by default runs in compatibility mode; that is, both SSH version 1 and SSH version 2 connections are honored.


Note

SSH version 1 is a protocol that has never been defined in a standard. If you do not want your device to fall back to the undefined protocol (version 1), you should use the ip ssh version command and specify version 2.

Use the ip ssh rsa keypair-name command to enable an SSH connection using Rivest, Shamir, and Adelman (RSA) keys that you have configured. If you configure the ip ssh rsa keypair-name command with a key-pair name, SSH is enabled if the key pair exists, or SSH will be enabled if the key pair is generated later. If you use this command to enable SSH, you do not need to configure a hostname and a domain name.

How to Configure NETCONF over SSHv2

Enabling SSH Version 2 Using a Hostname and Domain Name

Perform this task to configure your device for SSH version 2 using a hostname and domain name. You may also configure SSH version 2 by using the RSA key pair configuration (see Enabling SSH Version 2 Using RSA Key Pairs).

SUMMARY STEPS

    1.    enable

    2.    configure terminal

    3.    hostname hostname

    4.    ip domain-name name

    5.    crypto key generate rsa

    6.    ip ssh [timeout seconds | authentication-retries integer]

    7.    ip ssh version 2


DETAILED STEPS
     Command or ActionPurpose
    Step 1 enable


    Example:
    Device> enable
     

    Enables privileged EXEC mode.

    • Enter your password if prompted.

     
    Step 2 configure terminal


    Example:
    Device# configure terminal
     

    Enters global configuration mode.

     
    Step 3 hostname hostname


    Example:
    Device(config)# hostname host1
     

    Configures a hostname for your device.

     
    Step 4 ip domain-name name


    Example:
    Device(config)# ip domain-name domain1.com
     

    Configures a domain name for your device.

     
    Step 5 crypto key generate rsa


    Example:
    Device(config)# crypto key generate rsa
     

    Enables the SSH server for local and remote authentication.

     
    Step 6 ip ssh [timeout seconds | authentication-retries integer]


    Example:
    Device(config)# ip ssh timeout 120
     

    (Optional) Configures SSH control variables on your device.

     
    Step 7 ip ssh version 2


    Example:
    Device(config)# ip ssh version 2
     

    Specifies the version of SSH to be run on your device.

     

    Enabling SSH Version 2 Using RSA Key Pairs

    Perform this task to enable SSH version 2 without configuring a hostname or domain name. SSH version 2 will be enabled if the key pair that you configure already exists or if it is generated later. You may also configure SSH version 2 by using the hostname and domain name configuration. (See “Enabling SSH Version 2 Using a Hostname and Domain Name.)

    SUMMARY STEPS

      1.    enable

      2.    configure terminal

      3.    ip ssh rsa keypair-name keypair-name

      4.    crypto key generate rsa usage-keys label key-label modulus modulus-size

      5.    ip ssh [timeout seconds | authentication-retries integer]

      6.    ip ssh version 2


    DETAILED STEPS
       Command or ActionPurpose
      Step 1 enable


      Example:
      Device> enable
       

      Enables privileged EXEC mode.

      • Enter your password if prompted.

       
      Step 2 configure terminal


      Example:
      Device# configure terminal
       

      Enters global configuration mode.

       
      Step 3 ip ssh rsa keypair-name keypair-name


      Example:
      Device(config)# ip ssh rsa keypair-name sshkeys
       

      Specifies which RSA keypair to use for SSH usage.

      Note   

      A Cisco device can have many RSA key pairs.

       
      Step 4 crypto key generate rsa usage-keys label key-label modulus modulus-size


      Example:
      Device(config)# crypto key generate rsa usage-keys label sshkeys modulus 768
       

      Enables the SSH server for local and remote authentication on the device.

      For SSH version 2, the modulus size must be at least 768 bits.

      Note   

      To delete the RSA key pair, use the crypto key zeroize rsa command. After you have deleted the RSA command, you automatically disable the SSH server.

       
      Step 5 ip ssh [timeout seconds | authentication-retries integer]


      Example:
      Device(config)# ip ssh timeout 120
       

      Configures SSH control variables on your device.

       
      Step 6 ip ssh version 2


      Example:
      Device(config)# ip ssh version 2
       

      Specifies the version of SSH to be run on a device.

       

      Starting an Encrypted Session with a Remote Device

      Perform this task to start an encrypted session with a remote networking device. (You do not have to enable your device. SSH can be run in disabled mode.)

      From any UNIX or UNIX-like device, the following command is typically used to form an SSH session: 

      ssh -2 -s user@router.example.com netconf
      SUMMARY STEPS

        1.    Do one of the following:

        • ssh [-v {1 | 2}] [-c {3des| aes128-cbc | aes192-cbc| aes256-cbc}] [-m{hmac-md5 | hmac-md5-96 | hmac-sha1 | hmac-sha1-96}] [l userid] [-o numberofpasswordprompts n] [-p port-num] {ip-addr | hostname} [command]


      DETAILED STEPS
         Command or ActionPurpose
        Step 1Do one of the following:
        • ssh [-v {1 | 2}] [-c {3des| aes128-cbc | aes192-cbc| aes256-cbc}] [-m{hmac-md5 | hmac-md5-96 | hmac-sha1 | hmac-sha1-96}] [l userid] [-o numberofpasswordprompts n] [-p port-num] {ip-addr | hostname} [command]


        Example:
        Device# ssh -v 2 -c aes256-cbc -m hmac-sha1-96 -l user2 10.76.82.24


        Example:
        Device# 
ssh -v 2 -c aes256-cbc -m hmac-sha1-96 user2@10.76.82.24
         

        Starts an encrypted session with a remote networking device.

        The first example adheres to the SSH version 2 conventions. A more natural and common way to start a session is by linking the username with the hostname. For example, the second configuration example provides an end result that is identical to that of the first example.

         

        Troubleshooting Tips

        The ip ssh version command can be used for troubleshooting your SSH configuration. By changing versions, you can determine which SSH version has a problem.

        What to Do Next

        For more information about the ssh command, see the Cisco IOS Security Command Reference.

        Verifying the Status of the Secure Shell Connection

        Perform this task to display the status of the SSH connection on your device.


        Note

        You can use the following show commands in user EXEC or privileged EXEC mode.

        SUMMARY STEPS

          1.    enable

          2.    show ssh

          3.    show ip ssh


        DETAILED STEPS
           Command or ActionPurpose
          Step 1 enable


          Example:
          Device> enable
           

          (Optional) Enables privileged EXEC mode.

          • Enter your password if prompted.

           
          Step 2 show ssh


          Example:
          Device# show ssh
           

          Displays the status of SSH server connections.

           
          Step 3 show ip ssh


          Example:
          Device# show ip ssh
           

          Displays the version and configuration data for SSH.

           

          Examples

          The following output from the show ssh command displays status about SSH version 2 connections. 

          Device# show ssh
Connection Version Mode Encryption  Hmac                State          
Username
1          2.0     IN   aes128-cbc  hmac-md5     Session started       lab
1          2.0     OUT  aes128-cbc  hmac-md5     Session started       lab
%No SSHv1 server connections running.

          The following output from the show ip ssh command displays the version of SSH that is enabled, the authentication timeout values, and the number of authentication retries. 

          Device# show ip ssh
SSH Enabled - version 2.0
Authentication timeout: 120 secs; Authentication retries: 3

          Enabling NETCONF over SSHv2

          Perform this task to enable NETCONF over SSHv2.

          Before You Begin

          SSHv2 must be enabled.


          Note

          There must be at least as many vty lines configured as there are concurrent NETCONF sessions.


          Note
          • A minimum of four concurrent NETCONF sessions must be configured.
          • A maximum of 16 concurrent NETCONF sessions can be configured.
          • NETCONF does not support SSHv1.
          SUMMARY STEPS

            1.    enable

            2.    configure terminal

            3.    netconf ssh [acl access-list-number]

            4.    netconf lock-time seconds

            5.    netconf max-sessions session

            6.    netconf max-message size


          DETAILED STEPS
             Command or ActionPurpose
            Step 1 enable


            Example:
            Device> enable
             

            Enables privileged EXEC mode.

            • Enter your password if prompted.

             
            Step 2 configure terminal


            Example:
            Device# configure terminal
             

            Enters global configuration mode.

             
            Step 3 netconf ssh [acl access-list-number]


            Example:
            Device(config)# netconf ssh acl 1
             

            Enables NETCONF over SSHv2.

            • Optionally, you can configure an access control list for this NETCONF session.

             
            Step 4 netconf lock-time seconds


            Example:
            Device(config)# netconf lock-time 60
             

            (Optional) Specifies the maximum time, in seconds, a NETCONF configuration lock is in place without an intermediate operation.

            • The valid range is 1 to 300. The default value is 10 seconds.

             
            Step 5 netconf max-sessions session


            Example:
            Device(config)# netconf max-sessions 5
             

            (Optional) Specifies the maximum number of concurrent NETCONF sessions allowed.

            • The valid range is 4 to 16. The default value is 4.

             
            Step 6 netconf max-message size


            Example:
            Device(config)# netconf max-message 37283
             

            (Optional) Specifies the maximum size, in kilobytes (KB), for the messages received in a NETCONF session.

            • The valid range is 1 to 2147483. The default value is infinite.

            • To set the maximum size to infinite, use the no netconf max-message command.

             

            Configuration Examples for NETCONF over SSHv2

            Example: Enabling SSHv2 Using a Hostname and Domain Name

            configure terminal
hostname host1
ip domain-name example.com
crypto key generate rsa
ip ssh timeout 120
ip ssh version 2

            Enabling Secure Shell Version 2 Using RSA Keys Example

            The following example shows how to configure SSHv2 using RSA keys: 

            Device# configure terminal
            Device(config)# ip ssh rsa keypair-name sshkeys
            Device(config)# crypto key generate rsa usage-keys label sshkeys modulus 768
Device(config)# ip ssh timeout 120
Device(config)# ip ssh version 2

            Starting an Encrypted Session with a Remote Device Example

            The following example shows how to start an encrypted SSH session with a remote networking device, from any UNIX or UNIX-like device: 

            Device(config)# ssh -2 -s user@router.example.com netconf

            Configuring NETCONF over SSHv2 Example

            The following example shows how to configure NETCONF over SSHv2: 

            Device# configure terminal
Device(config)# netconf ssh acl 1
Device(config)# netconf lock-time 60
Device(config)# netconf max-sessions 5
Device(config)# netconf max-message 2345
Device# ssh-2 -s username@10.1.1.1 netconf

            The following example shows how to get the configuration for loopback interface 113.

            SUMMARY STEPS

              1.    First, send the “hello”:

              2.    Next, send the get-config request:


            DETAILED STEPS
               Command or ActionPurpose
              Step 1 First, send the “hello”:

              Example:
              <?xml version="1.0" encoding=\"UTF-8\"?>
<hello><capabilities>
     <capability>u?rn:ietf:params:netconf:base:1.0</capability>
      <capability>urn:ietf:params:netconf:capability:writeable-running:1.0</capability>
       <capability>urn:ietf:params:netconf:ca?pability:roll?back-on-error:1.0</capability>
        <capability>urn:ietf:params:netconf:capability:startup:1.0</capability>
         <capability>urn:ietf:params:netconf:ca?pability:url:?1.0</capability>
        <capability>urn:cisco:params:netconf:capability:pi-data-model:1.0</capability>
       <capability>urn:cisco:params:netconf:capabili?ty:notificati?on:1.0</capability>
   </capabilities>
</hello>]]>]]>
                              		 
              Step 2 Next, send the get-config request:

              Example:
              <?xml version="1.0"?>
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"xmlns:cpi="http://www.cisco.com/cpi_10/schema" 
message-id="101">
   <get-config> 
        <source> 
             <running/> 
         </source> 
          <filter> 
              <config-format-text-cmd>
               <text-filter-spec>
        interface Loopback113
                 </text-filter-spec>
              </config-format-text-cmd> 
          </filter> 
      </get-config> 
</rpc>]]>]]>
                              		 

              The following output is shown on the device: 
              <?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101"xmlns=\"urn:ietf:params:netconf:base:1.0\">
   <data>
      <cli-config-data>
interface Loopback113
description test456
no ip address
load-interval 30
end
       </cli-config-data>
    </data>
</rpc-rep?ly>]]>]]>

              Additional References for NETCONF over SSHv2

              Related Documents

              Related Topic

              Document Title

              Cicso IOS Commands

              Cisco IOS Master Command List, All Releases

              NETCONF commands: complete command syntax, command mode, command history, defaults, usage guidelines, and examples

              Cisco IOS Cisco Networking Services Command Reference

              IP access lists commands: complete command syntax, command mode, command history, defaults, usage guidelines, and examples

              Security commands: complete command syntax, command mode, command history, defaults, usage guidelines, and examples

              Cisco IOS Security Command Reference

              IP access lists

              IP Access List Overview and Creating an IP Access List and Applying It to an Interface modules in the Cisco IOS Security Configuration Guide: Securing the Data Plane.

              Secure Shell and Secure Shell Version 2

              “Configuring Secure Shell” module in the Cisco IOS Security Configuration Guide: Securing User Services.

              Standards and RFCs

              RFC

              Title

              RFC 2246

              The TLS Protocol Version 1.0

              RFC 4251

              The Secure Shell (SSH) Protocol Architecture

              RFC 4252

              The Secure Shell (SSH) Authentication Protocol

              RFC 4741

              NETCONF Configuration Protocol

              RFC 4742

              Using the NETCONF Configuration Protocol over Secure SHell (SSH)

              Technical Assistance

              Description

              Link

              The Cisco Support and Documentation website provides online resources to download documentation, software, and tools. Use these resources to install and configure the software and to troubleshoot and resolve technical issues with Cisco products and technologies. Access to most tools on the Cisco Support and Documentation website requires a Cisco.com user ID and password.

              Access to most tools on the Cisco Support website requires a Cisco.com user ID and password.

              http:/​/​www.cisco.com/​cisco/​web/​support/​index.html

              Feature Information for NETCONF over SSHv2

              The following table provides release information about the feature or features described in this module. This table lists only the software release that introduced support for a given feature in a given software release train. Unless noted otherwise, subsequent releases of that software release train also support that feature.

              Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/​go/​cfn. An account on Cisco.com is not required.
              Table 1 Feature Information for NETCONF over SSHv2

              Feature Name

              Releases

              Feature Information

              NETCONF over SSHv2

              Cisco IOS XE Release 2.1

              12.2(33)SB

              12.2(33)SRA

              12.2(33)SXI

              12.4(9)T

              The NETCONF over SSHv2 feature enables you to perform network configurations via the Cisco command-line interface (CLI) over an encrypted transport.

              The following commands were introduced or modified by this feature: netconf lock-time, netconf max-message, netconf max-sessions netconf ssh.