Beginning with Cisco NX-OS Release 10.2(3)F, you have the option of securely downloading the POAP script. When a device with the POAP feature boots and does not find the startup configuration, the device enters POAP mode, locates a DHCP server, and bootstraps itself with its interface IP address, gateway, and DNS server IP addresses. The device also obtains the IP address of an HTTPS server and downloads POAP script securely. The script enables the switch to download and install the appropriate software image and configuration file.

To download the POAP script securely, you need to select specific POAP options. Until Cisco NX-OS Release 10.2(3)F, POAP used options 66 and 67 for IPv4, and options 77 and 15 for IPv6 to extract the booting script information. However, the transfer of the script uses http, and is not very secure. Beginning with Cisco NX-OS Release 10.2(3)F, option 43 specifies the secure POAP related provisioning script information for IPv4 and option 17 specifies the same for IPv6. Additionally, these options allow the POAP to reach the file server in a secure manner. The POAP options 66, 67, 77, and 15 continue to be supported in Cisco NX-OS Release10.2(3)F. Furthermore, if you are using option 43 or 17, you can use the earlier options as fallback options, if required. From Cisco NX-OS Release 10.4(1)F, you can use Root-CA bundles instead of single .pem certificate for Secure POAP.

Note	The maximum character length is 512 bytes for both option 43 and option 17.

The sub-options available for option 43 and option 17 are discussed in the following sections:

• Option 43 - IPv4

• Option 17 - IPv6

 host dhclient-n9kv {
 hardware ethernet 00:50:56:85:c5:30;
 fixed-address 3.3.3.1;
 default-lease-time 3600;
 option broadcast-address 192.168.1.255;
 #option log-servers 1.1.1.1;
 max-lease-time 3600;
 option subnet-mask 255.255.255.0;
 option routers 10.77.143.1;
 #option domain-name-servers 1.1.1.1;
           vendor-option-space poap;
 option poap.version 1;
 option poap.ca_list "https://<ip>/poap/ca_file1.pem, https://<ip>/poap/ca_file2.pem";
 option poap.url "https://<url>/poap.py";
 option poap.debug 1;
 option poap.ntp 10.1.1.39;
 option poap.flag 0;
   }

 option dhcp6.next-hop-rt-prefix code 242 = { ip6-address, unsigned integer 16, 
unsigned integer 16, unsigned integer 32, unsigned integer 8, unsigned integer 8, ip6-address };
 option dhcp6.bootfile-url code 59 = string;
 
 default-lease-time 3600;
 max-lease-time 3600;
 log-facility local7;
 subnet6 2003::/64 {
 
   # This statement configures actual values to be sent
 # RTPREFIX option code = 243, RTPREFIX length = 22
 # Ignore value 22. It is something related to option-size RT_PREFIX option length.
 # lifetime = 9000 seconds
 # route ETH1_IPV6_GW/64
 # metric 1
 option dhcp6.next-hop-rt-prefix 2003::2222 243 22 9000 0 1 ::;
 #ipv6 ::/0 2003::2222
 #Another example - support not there in NXOS - CSCvs05271:
 #option dhcp6.next-hop-rt-prefix 2003::2222 243 22 9000 112 1 2003::1:2:3:4:5:0;
 #ipv6 2003::1:2:3:4:5:0/112 2003::2222
 
   # Additional options
 #option dhcp6.name-servers fec0:0:0:1::1;
 #option dhcp6.domain-search "domain.example";
 
 
 range6 2003::b:1111 2003::b:9999;
 option dhcp6.bootfile-url "tftp://2003::1111/poap_github_v6.py";
 vendor-option-space poap_v6;
 option poap_v6.version 1;
 option poap_v6.ca_list "https://<ip>/new_ca.pem,https://<ip>/another_ca.pem";
 option poap_v6.url "https://<ip>/poap_github_v4.py";
 option poap_v6.debug 1;
   }

POAP is enabled when there is no configuration in the system. It runs as a part of bootup. However, you can bypass POAP enablement during initial setup. If you want to disable POAP permanently (even when there is no configuration in the system), you can use the 'system no poap' command. This command ensures that POAP is not started during the next boot (even if there is no configuration). To enable POAP, use the 'system poap' command or the 'write erase poap' command. The 'write erase poap' command erases the POAP flag and enables POAP.

• Example: Disabling POAP

  
  switch# system no poap
  switch# sh boot
  Current Boot Variables:
   sup-1
  NXOS variable = bootflash:/nxos.9.2.1.125.bin
  Boot POAP Disabled
   
  POAP permanently disabled using 'system no poap'
   
   
  Boot Variables on next reload:
   
  sup-1
  NXOS variable = bootflash:/nxos.9.2.1.125.bin
  Boot POAP Disabled
   
  POAP permanently disabled using 'system no poap'
  
   
  switch# sh system poap
  System-wide POAP is disabled  using exec command 'system no poap'
  POAP will be bypassed on write-erase reload.
  (Perpetual POAP cannot be enabled when system-wide POAP is disabled)
   
  

• Example: Enabling POAP

  
  switch# system poap
  
  switch# sh system poap
  
  System-wide POAP is enabled
  

• Example: Erase POAP

  
  switch# write erase poap
  This command will erase the system wide POAP disable flag only if it is set.
  Do you wish to proceed anyway? (y/n)  [n] y
  System wide POAP disable flag erased.
  
  switch# sh system poap
  System-wide POAP is enabled
  

The reference script supplied by Cisco supports the following functionality:

• Retrieves the switch-specific identifier, for example, the serial number.

• Downloads the nx-os software image if the files do not already exist on the switch. The nx-os image is installed on the switch and is used at the next reboot.

• Schedules the downloaded configuration to be applied at the next switch reboot.

• Stores the configuration as the startup configuration.

Cisco has sample configuration scripts that were developed using the Python programming language and Tool Command Language (Tcl). You can customize one of these scripts to meet the requirements of your network environment. You can access the Python script to perform POAP on the Cisco Nexus 9000 Series switch at this link: https://github.com/datacenter/nexus9000/tree/master/nx-os/poap.

The Python programming language uses two APIs that can execute CLI commands. These APIs are described in the following table. The arguments for these APIs are strings of the CLI commands.

We provide a sample configuration script that is developed using the Python programming language. We recommend using the provided script and modifying it to meet the requirements of your network environment.

The POAP script can be found at https://github.com/datacenter/nexus9000/blob/master/nx-os/poap/poap.py.

To modify the script using Python, see the Cisco NX-OS Python API Reference Guide for your platform.

Before using the POAP script, perform the following actions:

1. Edit the options dictionary at the top of the script to ensure that all relevant options for your setup are included in the script. Do not change the defaults (in the default options function) directly.

2. Update the MD5 checksum of the POAP script as shown using shell commands.

   f=poap_nexus_script.py ; cat $f | sed '/^#md5sum/d' > $f.md5 ; sed -i "s/^#md5sum=.*/#md5sum=\"$(md5sum $f.md5 | sed 's/ .*//')\"/" $f
   
   

3. If the device has a startup configuration, perform a write erase and reload the device.

The following POAP script options can be specified to alter the POAP script behavior. When you download files from a server, the hostname, username, and password options are required. For every mode except personality, the target_system_image is also required. Required parameters are enforced by the script, and the script aborts if the required parameters are not present. Every option except hostname, username, and password has a default option. If you do not specify the option in the options dictionary, the default is used.

• username

  The username to use when downloading files from the server.

• password

  The password to use when downloading files from the server.

• hostname

  The name or address of the server from which to download files.

• mode

  The default is serial_number.

  Use one of the following options:

  • personality

    A method to restore the switch from a tarball.

  • serial_number

    The serial number of the switch to determine the configuration filename. The format for the serial number in the configuration file is conf.serialnumber. Example: conf.FOC123456

  • hostname

    The hostname as received in the DHCP options to determine the configuration filename. The format for the hostname in the configuration file is conf_hostname.cfg. Example: conf_3164-RS.cfg

  • mac

    The interface MAC address to determine the configuration filename. The format for the hostname in the configuration file is conf_macaddress.cfg. Example: conf_7426CC5C9180.cfg

  • raw

    The configuration filename is used exactly as provided in the options. The filename is not altered in any way.

  • location

    The CDP neighbors are used to determine the configuration filename. The format for the location in the configuration file is conf_host_intf.cfg, where host is the host connected to the device over the POAP interface, and intf is the remote interface to which the POAP interface is connected. Example: conf_remote-switch_Eth1_8.cfg

• required_space

  The required space in KB for that particular iteration of POAP. The default is 100,000. For multi-step upgrades, specify the size of the last image in the upgrade path of the target image.

• transfer_protocol

  Any transfer protocol such as http, https, ftp, scp, sftp, or tftp that is supported by VSH. The default is scp.

• config_path

  The path to the configuration file on the server. Example: /tftpboot. The default is /var/lib/tftpboot.

• target_system_image

  The name of the image to download from the remote server. This is the image you get after POAP completes. This option is a required parameter for every mode except personality. The default is "".

• target_image_path

  The path to the image on the server. Example: /tftpboot. The default is /var/lib/tftpboot.

• destination_path

  The path to which to download images and MD5 sums. The default is /bootflash.

• destination_system_image

  The name for the destination image filename. If not specified, the default will be the target_system_image name.

• user_app_path

  The path on the server where the user scripts, agents, and user data are located. The default is /var/lib/tftpboot.

• disable_md5

  This is True if MD5 checking should be disabled. The default is False.

• midway_system_image

  The name of the image to use for the midway system upgrade. By default, the POAP script finds the name of any required midway images in the upgrade path and uses them. Set this option if you prefer to pick a different midway image for a two-step upgrade. The default is "".

• source_config_file

  The name of the configuration file when raw mode is used. The default is poap.cfg.

• vrf

  The VRF to use for downloads and so on. The VRF is automatically set by the POAP process. The default is the POAP_VRF environment variable.

• destination_config

  The name to use for the downloaded configuration. The default is poap_replay.cfg.

• split_config_first

  The name to use for the first configuration portion if the configuration needs to be split. It is applicable only when the configuration requires a reload to take effect. The default is poap_1.cfg.

• split_config_second

  The name to use for the second configuration portion if the configuration is split. The default is poap_2.cfg.

• timeout_config

  The timeout in seconds for copying the configuration file. The default is 120. For non-legacy images, this option is not used, and the POAP process times out. For legacy images, FTP uses this timeout for the login process and not for the copy process, while scp and other protocols use this timeout for the copy process.

• timeout_copy_system

  The timeout in seconds for copying the system image. The default is 2100. For non-legacy images, this option is not used, and the POAP process times out. For legacy images, FTP uses this timeout for the login process and not for the copy process, while scp and other protocols use this timeout for the copy process.

• timeout_copy_personality

  The timeout in seconds for copying the personality tarball. The default is 900. For non-legacy images, this option is not used, and the POAP process times out. For legacy images, FTP uses this timeout for the login process and not for the copy process, while scp and other protocols use this timeout for the copy process.

• timeout_copy_user

  The timeout in seconds for copying any user scripts and agents. The default is 900. For non-legacy images, this option is not used, and the POAP process times out. For legacy images, FTP uses this timeout for the login process and not for the copy process, while scp and other protocols use this timeout for the copy process.

• personality_path

  The remote path from which to download the personality tarball. Once the tarball is downloaded and the personality process is started, the personality will download all files in the future from locations specified inside the tarball configuration. The default is /var/lib/tftpboot.

• source_tarball

  The name of the personality tarball to download. The default is personality.tar.

• destination_tarball

  The name for the downloaded personality tarball after it is downloaded. The default is personality.tar.

Beginning with Cisco NX-OS Release 7.0(3)I6(1), the tftp-server-name can be used without the DNS option. To enable POAP functionality without DNS on earlier releases, a custom option of 150 must be used to specify the tftp-server-address.

To use the tftp-server-address option, specify the following at the start of your dhcpd.conf file.

option tftp-server-address code 150 = ip-address;

For example:

host MyDevice {
    option dhcp-client-identifier "\000SAL12345678";
    fixed-address 2.1.1.10;
    option routers 2.1.1.1;
    option host-name "MyDevice";
    option bootfile-name "poap_nexus_script.py";
    option tftp-server-address 2.1.1.1;
}

The below example shows Configuring DHCPv6 for POAP over IPv6:

default-lease-time 3600;
max-lease-time 3600;
log-facility local7;
subnet6 2003::/64 {

        # This statement configures actual values to be sent
        # RTPREFIX option code = 243, RTPREFIX length = 22
        # Ignore value 22. It is something related to option-size RT_PREFIX option length.
        # lifetime = 9000 seconds
        # route ETH1_IPV6_GW/64
        # metric 1
        option dhcp6.next-hop-rt-prefix 2003::2222 243 22 9000 0 1 ::;
        #ipv6 ::/0 2003::2222
        #Another example - support not there in NXOS - CSCvs05271:
        #option dhcp6.next-hop-rt-prefix 2003::2222 243 22 9000 112 1 2003::1:2:3:4:5:0;
        #ipv6 2003::1:2:3:4:5:0/112 2003::2222

        # Additional options
        #option dhcp6.name-servers fec0:0:0:1::1;
        #option dhcp6.domain-search "domain.example";

        range6 2003::b:1111 2003::b:9999;
        #range6 2003::c:2222 2003::c:2222;
        option dhcp6.bootfile-url "tftp://2003::1111/poap_github_v6.py";

Under the options dictionary, you can find the download_scripts_and_agents function. If you choose to download user scripts and data, uncomment the first poap_log line and then use a series of download_user_app function calls to download each application. Since older Cisco NX-OS versions do not support recursive copy of directories, such directories must be put into a tarball (TAR archive) and then unpacked once on the switch. The parameters for the download_scripts_and_agents function are as follows:

• source_path - The path to where the file or tarball is located. This is a required parameter. Example: /var/lib/tftpboot.

• source_file - The name of the file to download. This is a required parameter. Example: agents.tar, script.py, and so on.

• dest_path - The location to download the file on the switch. Any directories that do not exist earlier will be created. This is an optional parameter. The default is /bootflash.

• dest_file - The name to give the downloaded file. This is an optional parameter. The default is unchanged source_file.

• unpack - Indicates whether a tarball exists for unpacking. Unpacking is done with tar -xf tarfile -C /bootflash . This is an optional parameter. The default is False.

• delete_after_unpack - Indicates whether to delete the downloaded tarball after unpack is successful. There is no effect if unpack is False. The default is False.

Using the download functionality, you can download all the agents and files needed to run POAP. To start the agents, you should have the configuration present in the running configuration downloaded by POAP. Then the agents, scheduler, and cron entry, along with EEM, can be used.

The POAP process has the following phases:

1. Power up

2. USB discovery

3. DHCP discovery

4. Script execution

5. Post-installation reload

Within these phases, other process and decision points occur. The following illustration shows a flow diagram of the POAP process.

The POAP personality feature, which is introduced in Cisco NX-OS Release 7.0(3)I4(1), enables user data, Cisco NX-OS and third-party patches, and configuration files to be backed up and restored. In previous releases, POAP can restore only the configuration.

The POAP personality is defined by tracked files on the switch. The configuration and package list in the personality file are ASCII files.

Binary versions are recorded in the personality file, but the actual binary files are not included. Because binary files are typically large, they are accessed from a specified repository.

The personality file is a .tar file, which would typically be extracted into a temporary folder. Here is an example:

switch# dir bootflash: 042516182843personality # timestamp name
46985 Dec 06 23:12:56 2015 running-config  Same as “show running-configuration” command.
20512 Dec 06 23:12:56 2015 host-package-list  Package/Patches list
58056 Dec 06 23:12:56 2015 data.tar  User Data
25    Dec 06 23:12:56 2015 IMAGEFILE  Tracked image metadata

During the POAP script execution phase, the personality module in the script restores the POAP personality, provided that the currently booted switch image is Cisco NX-OS Release 7.0(3)I4(1) or later. If necessary, upgrade the switch to the correct software image.

Note	A personality restore is done with the same software image used for the personality backup. Upgrading to a newer image is not supported through the POAP personality feature. To upgrade to a newer image, use the regular POAP script.

Note	If the personality script fails to execute for any reason (such as not enough space in the bootflash or a script execution failure), the POAP process returns to the DHCP discovery phase.

The restore process performs the following actions:

1. Untars and unzips the personality file in the bootflash.

2. Validates the personality file.

3. Reads the configuration and package list files from the personality file to make a list of the binaries to be downloaded.

4. If the current image or patches are not the same as specified in the personality file, downloads the binaries to the bootflash (if not present) and reboots with the correct image and then applies the packages or patches.

5. Unzips or untars the user data files relative to "/".

6. Copies the configuration file in the POAP personality to the startup configuration.

7. Reboots the switch.

The following sample POAP script (poap.py) includes the personality feature:

#md5sum="b00a7fffb305d13a1e02cd0d342afca3"
# The above is the (embedded) md5sum of this file taken without this line, # can be # created this way: 
# f=poap.py ; cat $f | sed '/^#md5sum/d' > $f.md5 ; sed -i "s/^#md5sum=.*/#md5sum=$(md5sum $f.md5 | sed 's/ .*//')/" $f # This way this script's integrity can be checked in case you do not trust # tftp's ip checksum. This integrity check is done by /isan/bin/poap.bin).
# The integrity of the files downloaded later (images, config) is checked # by downloading the corresponding file with the .md5 extension and is # done by this script itself.

from poap.personality import POAPPersonality import os

# Location to download system image files, checksums, etc.
download_path = "/var/lib/tftpboot"
# The path to the personality tarball used for restoration personality_tarball = "/var/lib/tftpboot/foo.tar"
# The protocol to use to download images/config protocol = "scp"
# The username to download images, the personality tarball, and the # patches and RPMs during restoration username = "root"
# The password for the above username
password = "passwd754"
# The hostname or IP address of the file server server = "2.1.1.1"

# The VRF to use for downloading and restoration vrf = "default"
if os.environ.has_key('POAP_VRF'):
    vrf = os.environ['POAP_VRF']

# Initialize housekeeping stuff (logs, temp dirs, etc.) p = POAPPersonality(download_path, personality_tarball, protocol, username, password, server, vrf)

p.get_personality()
p.apply_personality()

sys.exit(0)