Cisco APIC Installation and ACI Upgrade and Downgrade Guide

PDF

Cisco APIC Installation and ACI Upgrade and Downgrade Guide

Install Cisco APIC using a PXE server

Updated: July 12, 2026

Want to summarize with AI?

Log in

This topic explains how to install Cisco APIC using a PXE server, including required software, configuration steps, and troubleshooting notes for DNSMasq, HTTP, PXELINUX, and ISO extraction.

You can install Cisco Application Policy Infrastructure Controller ( APIC ) ISO for UEFI, UEFI SecureBoot, and Legacy BIOS systems using a PXE server.

Ensure that you have the following software installed on your system:

sudo apt install -y dnsmasq lighttpd syslinux-common pxelinux

DNSMasq Configuration

To create a new dnsmasq configuration, run the following command: 

$ sudo systemctl stop dnsmasq
                $ sudo mv /etc/dnsmasq.conf /etc/dnsmasq.conf.orig
                $ sudo mkdir -p /srv/tftp

In the following code snippet, you must enter the IP details of your HTTP server that is hosting ISO and then configure a DHCP subnet range for clients which must be able to reach the HTTP server's IP. After you save your configuration file with the changes, run the following command:

sudo systemct restart dnsmasq
interface=*
                bind-interfaces
                enable-tftp
                tftp-root=/srv/tftp
                port=0
                log-dhcp
                dhcp-no-override
                dhcp-match=x86PC,  option:client-arch, 0  # matches legacy BIOS x86
                dhcp-match=BC_EFI, option:client-arch, 7  # matches UEFI x86-64
                # Load different PXE boot image depending on client architecture
                pxe-service=tag:x86PC,X86PC,   "Install Linux on x86 BIOS",    pxelinux.0
                pxe-service=tag:BC_EFI,BC_EFI, "Install Linux on x86-64 UEFI", bootx64.efi
                # Set bootfile name only when tag is "bios" or "uefi"
                dhcp-boot=tag:x86PC,pxelinux.0      # for Legacy BIOS detected by dhcp-match above
                dhcp-boot=tag:BC_EFI,bootx64.efi    # for UEFI arch detected by dhcp-match above
                # Enable PXELinux client options
                dhcp-option=tag:x86PC,208,f1:00:74:7e  # pxelinux.magic string
                # set boot params, note the ip/network is tied to the netplan config in this layer
                dhcp-option-force=129,"atxi.wipe=true atomix.isourl=http://<IP of your HTTP server>/atomix.iso"
                # an example IPV4 subnet range
                dhcp-range=192.168.41.3,192.168.41.50,12h
                dhcp-lease-max=25

HTTP Configuration

The default lighttpd configuration file will work as it is with no changes required as it listens on all interfaces for port 80.

Note

The name of the file must match the /etc/dnsmasq.conf value in the dhcp-option-force=129 setting. This value is passed into the machine through the DHCP settings and will use the URL to download the iso file.

Copy the installer iso file to following path:

/var/www/html/<ISONAME.iso>

PXELINUX Configuration

Systems that reboot through BIOS/Legacy uses pxelinux to acquire the installer. Ensure that the tftp location in the DNSMasq configuration file above is used to copy these files and configurations or adjust the commands as needed. 

sudo mkdir -p /srv/tftp
                sudo cp -av /usr/lib/PXELINUX/* /srv/tftp/
                sudo cp /usr/lib/syslinux/modules/bios/* /srv/tftp/
                sudo mkdir -p /srv/tftp/pxelinux.cfg

Copy the following configuration to this /srv/tftp/pxelinux.cfg/default location and modify the HTTP URL to match the HTTP server’s IP and path to the ISO. 

DEFAULT atomix-install
                label atomix-install
                kernel vmlinuz
                append initrd=initrd.img ro verbose debug console=tty0 console=ttyS0,115200n8 atomix.isourl=http://<HTTP_IP>/<ISO NAME>
                sysappend 3

Extracting content from ISO

Once you’ve acquired the ISO, you need to extract some files from the ISO and place them in certain directories, as shown below:

$ sudo mkdir /mnt/iso /mnt/efi
                $ sudo mount -oloop /var/www/html/<ISO filename> /mnt/iso
                $ sudo mount -t vfat /mnt/iso/images/efiboot.img /mnt/efi
                $ cp -av /mnt/efi/EFI/BOOT/BOOTX64.efi /srv/tftp/bootx64.efi
                $ cp -av /mnt/efi/EFI/BOOT/GRUBX64.efi /srv/tftp/grubx64.efi
                $ cp -av /mnt/iso/isolinux/vmlinuz /srv/tftp/vmlinuz
                $ cp -av /mnt/iso/isolinux/initrd.img /srv/tftp/initrd.img
                $ sudo umount /mnt/efi
                $ sudo umount /mnt/iso

Testing

Once you apply the configuration, your test systems must boot into the installer and configure the networking settings and download the ISO through HTTP to the system and proceed with the install.

On the PXE server, you can use the following dnsmasq service: 

sudo journalctl --follow -u dnsmasq
Note

Some of the dnsmasq log entries may display an error as shown below. However, these errors are not fatal and the UEFI PXE clients in the firmware will try again. 

Feb 17 01:01:25 ubuntu dnsmasq-dhcp[1201]: 1836224829 sent size: 10 option: 43 vendor-encap  06:01:08:0a:04:00:50:58:45:ff
                    Feb 17 01:01:25 ubuntu dnsmasq-tftp[1201]: error 8 User aborted the transfer received from 192.168.41.3
                    Feb 17 01:01:25 ubuntu dnsmasq-tftp[1201]: failed sending /srv/tftp/bootx64.efi to 192.168.41.3
                    Feb 17 01:01:25 ubuntu dnsmasq-tftp[1201]: sent /srv/tftp/bootx64.efi to 192.168.41.3
                    Feb 17 01:01:47 ubuntu dnsmasq-tftp[1201]: error 3 User provided memory block is too small received from 192.168.41.3
                    Feb 17 01:01:47 ubuntu dnsmasq-tftp[1201]: failed sending /srv/tftp/grubx64.efi to 192.168.41.3
                    Feb 17 01:02:09 ubuntu dnsmasq-tftp[1201]: sent /srv/tftp/grubx64.efi to 192.168.41.3

On the PXE client, the serial console output shows the install and in particular displays how it acquires the ISO.

This is part of the installer output that displays how it acquires the installer iso file. 

++ cmdline=' BOOT_IMAGE=vmlinuz initrd=initrd.img ro verbose debug console=tty0 console=ttyS0,115200n8 atomix.isourl=http://192.168.41.2/atomix.iso ip=192.168.41.41:192.'
                ++ case "$cmdline" in
                ++ val='http://192.168.41.2/atomix.iso ip=192.168.41.41:192.168.41.2:192.168.41.2:255.255.255.0 BOOTIF=01-52-54-00-12-34-56 '
                ++ val=http://192.168.41.2/atomix.iso
                ++ echo http://192.168.41.2/atomix.iso
                + ksurl=http://192.168.41.2/atomix.iso
                + '[' -z http://192.168.41.2/atomix.iso ']'
                + '[' -n http://192.168.41.2/atomix.iso ']'
                + '[' -z '' ']'
                + dhclient
                [    3.573160] 8021q: adding VLAN 0 to HW filter on device ens4
                + tmpiso=/tmp/atomix.iso
                ++ seq 1 3
                + for count in $(seq 1 3)
                + '[' http: = https ']'
                + busybox wget --output-document=/tmp/atomix.iso http://192.168.41.2/atomix.iso
                Connecting to 192.168.41.2 (192.168.41.2:80)
                atomix.iso           100% |********************************|  842M  0:00:00 ETA
                + break
                + mkdir -p /cdrom
                + mount -o loop,ro /tmp/atomix.iso /cdrom
                [    4.896038] ISO 9660 Extensions: RRIP_1991A
                + echo 'Found install image through PXE'
                Found install image through PXE
                ...