GNU Copyright Statement

Chapter 1. Understanding the Command-Line Interface

About the Application Policy Infrastructure Controller

Configuration Options

Understanding Managed Objects

Understanding the File System

Understanding the GNU Bash Shell

Bash Extensions

Networking Naming Conventions

Interface Naming

Network Address Naming

Command Completion

Command History

Command Help

Mount Points

aci Mount Point

mit Mount Point

debug Mount Point

Role-Based Access Control

Applying Permissions and Security

User Management

Chapter 2. Using the APIC CLI

Accessing the Object Model CLI

Viewing Managed Objects

Navigating the Management Information Tree

MO Browser Utility

Entering a Configuration

Displaying Command Differences

Using Configuration Wizards

Skipping Properties

Creating Configuration Templates

Creating Templates Using the moconfig Command

Creating Templates using Configuration Wizards

Customizing Commands

Sample YAML Command Definitions

YAML File Format

Chapter 3. Command Reference

Command Help

attach

auditlog

create

controller

diagnostics

eraseconfig

eventlog

faults

firmware

health

loglevel

man

mobrowser

moconfig

mocreate

modelete

mofind

moprint

moquery

moset

mostats

password

reload

scope

show

svcping

techsupport

trafficmap

troubleshoot eptoep session (IP and MAC)

troubleshoot epext session EP-to-External-IP and External-IP-to-EP

troubleshoot eptoep session <session name>

troubleshoot eptoep session <session name> atomiccounter

troubleshoot eptoep session <session name> traceroute

troubleshoot eptoep session <session name> traceroute protocol

troubleshoot eptoep session <session name> traceroute protocol tcp dst port

show troubleshoot eptoep

show troubleshoot eptoep session <session name>

version

where

Preface

Audience

Document Conventions

Related Documentation

Documentation Feedback

GNU Copyright Statement

Please send general FSF & GNU inquiries to gnu@gnu.org. There are also other ways to contact the FSF. Please send broken links and other corrections or suggestions to bug-bash@gnu.org. Please see the Translations README for information on coordinating and submitting translations of this article.

Copyright © 2007, 2009, 2011 Free Software Foundation, Inc. Verbatim copying and distribution of this entire article are permitted worldwide, without royalty, in any medium, provided this notice, and the copyright notice, are preserved. Updated: Date: 2011/06/28 02:44:32

Chapter 1. Understanding the Command-Line Interface

- About the Application Policy Infrastructure Controller

- Configuration Options

- Understanding Managed Objects

- Understanding the File System

About the Application Policy Infrastructure Controller

This guide describes how to use the command-line interface (CLI) of the Application Policy Infrastructure Controller (APIC), which consists of the standard Bash command language interpreter shell plus a set of custom commands for the APIC.

For detailed reference information about API classes, methods, and types, see the Cisco APIC Management Information Model Reference, which is a web-based application. To learn about the features and operation of the Application Policy Infrastructure Controller, see the available white papers and the Cisco Application Centric Infrastructure Fundamentals.

Configuration Options

The Cisco Application Policy Infrastructure Controller (APIC) offers the following configuration options:

- Direct Configuration with the Object Model CLI—You can use the Object Model CLI extensions to the BASH shell to directly manipulate managed objects (MO) and the Management Information Tree (MIT). This document provides information about direct configuration using the Object Model CLI.

- NX-OS Style CLI—Beginning with Cisco APIC Release 1.2, you can use NX-OS style CLI commands for configuration.

Note

This document does not provide information about the APIC NX-OS style CLI interface. For information, see Cisco APIC NX-OS Style Command-Line Interface Configuration Guide.

- Shell Scripts— You can use the Bash shell to automate some tasks using shell scripting. For more information about Bash, see Understanding the GNU Bash Shell.

- Python API— Enables more extensive automation. For more information about the Python API, see the Cisco APIC Python SDK Reference.

Note

From Cisco APIC Release 1.0 until Release 1.2, the Object Model CLI was the default CLl, appearing when you logged in to APIC using SSH. Beginning with Cisco APIC Release 1.2, the default CLI is the NX-OS style CLI. The object model CLI is available by typing the bash command at the initial CLI prompt.

Understanding Managed Objects

The APIC system configuration and state are modeled as a collection of managed objects (MOs), which are abstract representations of a physical or logical entity that contain a set of configurations and properties. For example, servers, chassis, I/O cards, and processors are physical entities represented as MOs; resource pools, user roles, service profiles, and policies are logical entities represented as MOs.

At runtime all MOs are organized in a tree structure called the Management Information Tree, providing structured and consistent access to all MOs in the system.

Understanding the File System

The Management Information Tree (MIT) consists of hierarchically organized MOs that allow you to manage the APIC. Each MO is modeled as a Linux directory that contains all child MOs as subdirectories and all properties in an mo file.

Here is a sample output of the file system: the local-users directory contains subdirectories for three users: admin, john, and viewer.

admin@apic1:local-users> pwd
/home/admin/aci/admin/aaa/security-management/local-users
admin@apic1:local-users> ls -al
total 3
drw-rw---- 1 admin admin 512 Apr 10 16:58 .
drw-rw---- 1 root  root  512 Apr  8 07:06 ..
drw-rw---- 1 root  root  512 Apr  8 07:06 admin
drw-rw---- 1 admin admin 512 Jan 28 20:16 john
-r--r----- 1 admin admin 197 Apr 10 16:58 summary

Role based access controls (RBAC) allow you to grant permissions to a user so that the user can manage another user. In this case, admin and viewer users are owned by root, while john is owned by admin.

Note

The absence of an mo file in this directory indicates that there are no configurable properties at this directory level.

admin@apic1:local-users> cd admin
admin@apic1:admin> pwd
/home/admin/aci/admin/aaa/security-management/local-users/admin
admin@apic1:admin> ls -al
total 4
drw-rw---- 1 admin admin 512 Jul 22 14:29 .
drw-rw---- 1 admin admin 512 Jul 22 14:29 ..
-rw-rw---- 1 admin admin 485 Jul 22 14:29 mo
drw-rw---- 1 admin admin 512 Jul 22 14:29 operational
drw-rw---- 1 admin admin 512 Jul 22 14:29 security-domains
drw-rw---- 1 admin admin 512 Jul 22 14:29 ssh-keys
-r--r----- 1 admin admin 493 Jul 22 14:29 summary
drw-rw---- 1 admin admin 512 Jul 22 14:29 user-certificates

- Understanding the GNU Bash Shell

- Bash Extensions

- Mount Points

- Role-Based Access Control

Understanding the GNU Bash Shell

Bash (Bourne Again SHell) is a Unix shell or command-line interpreter supported by a variety of operating systems. You can use the Bash interface to directly configure the APIC or develop Bash shell scripts to automate tasks. Bash provides a variety of command line and scripting features.

Synopsis

Bash is an sh-compatible command language interpreter that executes commands read from the standard input or from a file. Bash also incorporates useful features from the Korn and C shells (ksh and csh). Bash is ultimately intended to be a faithful implementation of the IEEE POSIX Shell and Tools specification (IEEE Working Group 1003.2).

Bash supports a variety of features including:

- Command-line editing

- Unlimited size command history

- Job control

- Shell functions and aliases

- Indexed arrays of unlimited size

- Integer arithmetic in any base from 2 to 64

For more information about the Bash shell , see Click Here .

Bash Extensions

The APIC includes following extensions of the Bash shell:

- Networking Naming Conventions

- Command Completion

- Command History

- Command Help

Networking Naming Conventions

Network operating systems typically use a forward slash (/) as a separator for interfaces, network addresses, and other settings. However, the Bash shell restricts the use of the forward slash in file names. While Bash provides for an escape character, the APIC file system simplifies network naming by using a colon (:) as a separator. The following examples describe how to use this separator.

- Interface Naming

- Network Address Naming

Interface Naming

The APIC Bash extension uses the colon (:) character to delimit interface names. For example, the interface Ethernet 1/46 is written as eth1:46.

The following example shows output of interfaces on a node:

admin@apic1:physical-interfaces> pwd
/aci/fabric/inventory/fabric-pod-1/fabric-node-17/interfaces/physical-interfaces
admin@apic1:physical-interfaces> ls
eth1:1   eth1:17  eth1:24  eth1:31  eth1:39  eth1:46  eth1:53  eth1:60
eth1:10  eth1:18  eth1:25  eth1:32  eth1:4   eth1:47  eth1:54  eth1:7
eth1:11  eth1:19  eth1:26  eth1:33  eth1:40  eth1:48  eth1:55  eth1:8
eth1:12  eth1:2   eth1:27  eth1:34  eth1:41  eth1:49  eth1:56  eth1:9
eth1:13  eth1:20  eth1:28  eth1:35  eth1:42  eth1:5   eth1:57  summary
eth1:14  eth1:21  eth1:29  eth1:36  eth1:43  eth1:50  eth1:58
eth1:15  eth1:22  eth1:3   eth1:37  eth1:44  eth1:51  eth1:59
eth1:16  eth1:23  eth1:30  eth1:38  eth1:45  eth1:52  eth1:6
admin@apic1:physical-interfaces>

Network Address Naming

The APIC Bash extension uses the colon (:) character to delimit network addresses. For example, the network 192.168.1.0 and subnet 255.255.255.0 are written as follows:

192.168.1.0:255.255.255.0

Command Completion

The APIC provides tab completion for standard Linux commands and APIC-specific commands listed in the Command Reference. When you press the Tab key at the end of a command or option abbreviation, the CLI displays the command in full or the next available keyword or argument choice.

For example, you can use the tab key to display available directories:

admin@apic1:aci> cd tenants/ <Tab>
common/ infra/  mgmt/

Command History

The APIC CLI supports the Bash shell history functions. To display the command history, you can use the Up Arrow or Down Arrow, as well as the history command.

You can reenter a command in the history by stepping through the history to recall the desired command and pressing Enter. You can also recall a command and change it before you enter it.

In addition, you can directly search for a previous command by pressing Ctrl-r and then typing part of the desired command until the command is displayed.

For more information about the Bash shell including additional command history functions, see Click Here

Command Help

The CLI provides two forms of context sensitive help:

- Inline help—At any time, you can enter the Esc key twice to display the options available at the current state of the command syntax. If you have not entered anything at the prompt, entering Esc key twice lists all available commands for the current command mode. If you have partially entered a command, entering Esc key twice lists all available keywords and arguments available at your current position in the command syntax.

- Man pages—At the command prompt, you can enter the man followed by a command or path to a managed object (MO) under /aci to display a UNIX-style man page. Man pages are not available for all commands or scopes.

Mount Points

The APIC CLI has three mount points: aci, mit, and debug. The following sections describe the mount points in more detail.

When you log into the APIC, the aci, debug, and mit mount points are displayed default directory:

admin@apic1:~> ls
aci  debug  mit

Note

A link to each file system is provided in each user home directory.

The following sections describe the mount points in more detail.

- aci Mount Point

- mit Mount Point

- debug Mount Point

aci Mount Point

The aci file system organizes MOs and properties into a concise format for interactive user sessions. The aci mount point is intended for most users and is the primary CLI interface for the APIC.

mit Mount Point

The Management Information Tree (MIT) file system allows advanced users to directly view and configure MOs within the MIT. The directory structure of the mitfs is the same as aci except that MOs are displayed as native MIT objects.

For example, the mit mount point displays the admin user as follows:

admin@apic1:user-admin> pwd
/mit/uni/userext/user-admin
admin@apic1:user-admin> ls -ltr
total 4
drw-rw---- 1 root  root  512 Jan 27 15:08 userdomain-all
drw-rw---- 1 root  root  512 Jan 27 15:08 userdata
-r--r----- 1 root  root  665 Jan 27 15:08 mo
drw-rw---- 1 admin admin 512 Jan 28 17:56 history
drw-rw---- 1 admin admin 512 Jan 28 17:56 faults

Note

The mit mount point is intended for advanced users with a strong understanding of MO configuration.

debug Mount Point

The debug mount point allows you to view and debug configurations across multiple APIC, leaf, and spine devices. The debug mount point is intended for troubleshooting by advanced users.

Role-Based Access Control

With role-based access control (RBAC), you can limit access to device operations by assigning roles to users. You can customize access and restrict it to users who require it.

- Applying Permissions and Security

- User Management

Applying Permissions and Security

Role-Based Access Control (RBAC) allows you to control user permissions by creating roles with a set of permissions and assigning them to users. RBAC allows you to apply permission to a user by assigning a role rather than directly configuring permissions.

Within the APIC CLI, you can grant permissions to users to manipulate specific parts of the Management Information Tree (MIT) such as a managed object (MO).

The following example shows how to use the ls command to display RBAC permissions within the APIC CLI. The command output displays files and UNIX read/write/execute file permissions and the time and date when the file was last modified.

admin@apic1:user-admin> ls -al
total 4
drw-rw---- 1 admin admin 512 Jul 22 14:25 .
drw-rw---- 1 admin admin 512 Jul 22 14:25 ..
-rw-rw---- 1 admin admin 421 Jul 22 14:25 mo
-r--r----- 1 admin admin 608 Jul 22 14:25 summary
drw-rw---- 1 admin admin 512 Jul 22 14:25 userdata
drw-rw---- 1 admin admin 512 Jul 22 14:25 userdomain-all

User Management

By default, each user is provided with a home directory at /home/<username>. This directory gives permissions for a user to create sub-directories and files. Files created within /home/<username> inherit the default umask permissions and are accessible by the user and the administrator (admin).

We recommend that users create a /userid directory to store files- such as /home/jsmith -when logging in for the first time. Thereafter the APIC treats the /userid directory as the user's home directory.

Chapter 2. Using the APIC CLI

- Accessing the Object Model CLI

- Viewing Managed Objects

- Navigating the Management Information Tree

- Entering a Configuration

- Using Configuration Wizards

- Creating Configuration Templates

- Customizing Commands

Accessing the Object Model CLI

Note

From Cisco APIC Release 1.0 until Release 1.2, the Object Model CLI was the default CLl, appearing when you logged in to APIC using SSH. Beginning with Cisco APIC Release 1.2, the default CLI is the NX-OS style CLI.

Procedure

Step 1

From a secure shell (SSH) client, open an SSH connection to APIC at username@ip-address. Use the administrator login name and the out-of-band management IP address that you configured during the initial setup. For example, admin@192.168.10.1.

Step 2

When prompted, enter the administrator password.

Step 3

At the command line prompt, type bash.

Example

This example shows how to reach the object model CLI from the initial CLI prompt.

apic1# bash
admin@apic1:~>

Viewing Managed Objects

Use the cat summary command to display a summary of the managed object (MO) in a given context within the Management Information Tree (MIT):

Note

You can also use the less and more commands to displayMO files one screen at a time.

admin@apic1:common> cat summary
name               : common
description        :
tags               : uni/tn-common
ownerkey           :
ownertag           :
alias              :
monitoring-policy  :
epg-address-pool   :

security-domains:
name    description
------  -----------
common

Navigating the Management Information Tree

The Management Information Tree (MIT) contains a variety of scopes, including:

- aaa

- auditlog

- controller

- eventlog

- fabric-policies

- faults

- faults-history

- firmware

- health

- health-history

- import-export

- l4-l7-inventory

- l4-l7-packages

- local-user

- pod

- schedulers

- security-domains

- switch

- tenant

- trafficmap

- version

- vm-inventory

- vm-policies

To navigate quickly through these scopes, you can use the following commands:

- scope—Jumps to the directory for a context.

- show—Displays the summary for a context.

- where—Displays the management information tree (MIT) directory path for a context.

For more information about these commands, see Command Reference

- MO Browser Utility

MO Browser Utility

The APIC CLI contains a managed object (MO) browser utility for viewing and editing MOs with a interface similar to vi. For more information about mobrowser, see mobrowser.

Entering a Configuration

You can use the moconfig, moset, and modelete commands to create a configuration.

The moconfig command creates a new context by name, whereas moset sets properties on an existing MO. The modelete command removes a scope by name, typically a sub-scope.

To override default settings, you can specify additional properties with the mocreate command. If you want to override default settings for a context, you can specify additional properties with the mocreate command. For more information, see mocreate.

Note

You can also use the APIC GUI, REST API, or Python API to enter a configuration. For more information about these tools, see the APIC Getting Started Guide and the APIC Python API and SDK.

- Displaying Command Differences

Displaying Command Differences

The moconfig diff command summarizes any unsaved changes are present in the configuration buffer. You can use the moconfig commit command to apply the new properties to the MO.

Using Configuration Wizards

Wizards simplify the process of creating a configuration. When you run a wizard in a given context (such as tenants), the wizard helps you create a complete configuration within a given context (for example, tenants or private networks).

Launching a Wizard

To start a wizard, run the .wiz file. For example, the tenant context provides a wizard that you can run using the ./tenant.wiz Bash command.

Wizard Options

Wizards support command completion. You can enter ? to list the available options.

description       : MyCompany BD
network           : ?
default          network
inb              network
overlay-1        network
network           : inb

Example

The following example shows the full output of the tenant wizard.

admin@apic1:tenants> ./tenant.wiz

tenant
------
name              : MyCompany
alias             : MyCompany_tenant
description       : This is MyCompany
monitoring-policy : default

private-network
---------------
name              : MyCompany_net
description       : MyCompany Network
bgp-timers        : default
ospf-timers       : default
monitoring-policy : default

bridge-domain
---------------
name              : MyCompany_domain
description       : MyCompany BD
network           : ?
default          network
inb              network
overlay-1        network
network           : inb

Do you want to create another private-network (y/n): n

Do you want to view the corresponding commands? (y/n): y
--------------------------------------------------------------------------------

mocreate MyCompany
cd MyCompany
moset alias MyCompany_tenant
moset description This is MyCompany
moset monitoring-policy default
cd /aci/tenants/MyCompany/networking
cd /aci/tenants/MyCompany/networking/private-networks
mocreate MyCompany_net
cd MyCompany_net
moset description MyCompany Network
moset bgp-timers default
moset ospf-timers default
moset monitoring-policy default
cd /aci/tenants/MyCompany/networking/bridge-domains
mocreate MyCompany_domain
cd MyCompany_domain
moset description MyCompany BD
moset network inb
cd /aci/tenants/MyCompany/networking/private-networks/MyCompany_net
cd /aci/tenants/MyCompany/networking
cd /aci/tenants/MyCompany

Do you want to commit changes? (y/n): y

Committing all the mos...
Committed mo tenants/MyCompany
Committed mo tenants/MyCompany/networking/private-networks/MyCompany_net
Committed mo tenants/MyCompany/networking/bridge-domains/MyCompany_domain
done
admin@apic1:tenants>

- Skipping Properties

Skipping Properties

You can use the Ctrl+N command to skip options within a wizard.

Note

Wizards dynamically track missing properties. If you skip a property, you can run the appropriate wizard to complete the configuration later. For example, if you run the tenant wizard, you can skip properties within the private-network context:

admin@apic1:tenants> ./tenant.wiz
<output truncated>
private-network
---------------
name              : Company_net
description       : s...skipping
bgp-timers        : s...skipping
ospf-timers       : s...skipping
monitoring-policy : s...skipping

bridge-domain
---------------

name              : default

<output truncated>

Later, you can run the private-network wizard later to complete the configuration.

admin@apic1:networking> ls
bridge-domains             external-routed-networks  fv-tenant-common  fv-tenant-mgmt  private-network.wiz  protocol-policies
external-bridged-networks  fv-tenant-MyCompany            fv-tenant-infra   fv-tenant-test  private-networks
admin@apic1:networking> ./private-network.wiz

Creating Configuration Templates

Configuration templates allow you to create reusable network configurations that you can apply using orchestration tools, shell scripts, and other tools. The following sections describe how to use the APIC CLI to create configuration templates.

- Creating Templates Using the moconfig Command

- Creating Templates using Configuration Wizards

Creating Templates Using the moconfig Command

The moconfig command simplifies the process of creating configuration templates. When you create a configuration using the GUI, CLI, or API, you can use the moconfig running command to display the resulting configuration in a given context.

For example, you can use the GUI to create a tenant configuration including the following properties:

- Name

- Alias

- Description

- Tags

- Monitoring Policy

- Security Domains

After you enter the configuration in the GUI, you can use the moconfig command in the new APIC context to display the commands that make up the configuration. For example, if you create a new tenant MyCompany, you can display the configuration commands as follows:

admin@apic1:tenants> ls
common  infra  mgmt  MyCompany  tenant.wiz
admin@apic1:tenants> cd MyCompany/
admin@apic1:MyCompany> moconfig running
cd /aci/viewfs/tenants
mocreate MyCompany
cd MyCompany
moset description 'My Company Network'
moset alias Home
moset monitoring-policy default
moconfig commit
cd networking
cd private-networks
mocreate local_net
cd local_net
moset description 'Local network'
moset bgp-timers default
moset ospf-timers default
moset monitoring-policy default
moconfig commit
cd ..
cd ..
cd bridge-domains
mocreate BD1
cd BD1
moset description 'Bridge domain 1'
moset custom-mac-address 00:22:BD:F8:19:FF
moset arp-flooding no
moset unicast-routing yes
moset network overlay-1
moconfig commit
cd ..
cd ..
cd ..
cd ..
admin@apic1:MyCompany>

For more information about using the moconfig running command, see the moconfig command. .

Creating Templates using Configuration Wizards

When running a configuration wizard, you can use the corresponding commands option to summarize the configuration created by the wizard. You can modify and replicate this configuration on other nodes or devices.

The following example shows how to display the command output from a configuration wizard.

Note

The command output is truncated.

admin@apic1:tenants> ./tenant.wiz

<Output truncated>

Do you want to create another private-network (y/n): n

Do you want to view the corresponding commands? (y/n): y
--------------------------------------------------------------------------------
mocreate MyCompany
cd MyCompany
moset alias Home
moset description My Company Network
moset monitoring-policy default
cd /aci/tenants/MyCompany/networking
cd /aci/tenants/MyCompany/networking/private-networks
mocreate local_net
cd local_net
moset description Local network
moset bgp-timers default
moset ospf-timers default
moset monitoring-policy default
cd /aci/tenants/MyCompany/networking/bridge-domains
mocreate BD1
cd BD1
moset description Bridge domain 1
moset network overlay-1
cd /aci/tenants/MyCompany/networking/private-networks/local_net
cd /aci/tenants/MyCompany/networking
cd /aci/tenants/MyCompany
--------------------------------------------------------------------------------
<Output truncated>

For more information about using wizards, see Configuration Wizards.

Customizing Commands

The APIC CLI allows you to extend Linux commands in the Bash interface using YAML (.yml) files in the /etc/scopedefs directory. YAML configuration files specify Linux commands to run and available options at each scope.

You can use YAML files to create new commands and extend existing Linux commands. YAML files allow you to define custom interfaces for users by placing a unique .yml file in the user's scope in the MIT.

You can customize the following commands using YAML.

- show—Displays the APIC configuration in a format similar to Cisco IOS and NX-OS. For more information, see show.

- create— Executes a wizard within a given scope; the wizard creates relevant objects in the MIT. For more information, see create.

- where—Displays the directory for a context, such as tenant or l4-l7-services. For more information, see where.

- scope—To jump to the directory for a context, such as tenant or l4-l7-services. For more information, see scope.

- attach—Opens an SSH session to a specified fabric node. For more information, see attach.

- Sample YAML Command Definitions

- YAML File Format

Sample YAML Command Definitions

controller Command

The following example shows the controller command output:

admin@apic1:aci> controller

operational-cluster-size                                 : 3
differences-between-local-time-and-unified-cluster-time  : 0
administrative-cluster-size                              : 3

controllers:
id  name   ip        cluster-admin-state  cluster-operational-  health-state  up-time          system-current-time
state
--  -----  --------  -------------------  --------------------  ------------  ---------------  ---------------------
1   apic1  10.0.0.1  in-service           available             fully-fit     62:02:38:00.000  2014-05-
01T21:40:46.120+00:00
2   apic2  10.0.0.2  in-service           available             fully-fit     62:02:38:00.000  2014-05-
01T21:40:46.211+00:00
3   apic3  10.0.0.3  in-service           available             fully-fit     62:02:38:00.000  2014-05-
01T21:40:46.263+00:00

The following example shows the YAML definition of the controller command:

- controller:
help: 'Controller Node'
type: alias
dirFormat: '/aci/system/controllers/'
fileType: 'summary'
sub:
- name: id
label: id
type: arg
modelclass: fabric.Node
modelprop: id
classfilter: 'fabric.Node.role == "1"'
dirFormat: '/aci/system/controllers/%(id)s'
fileType: 'summary'
help: 'controller'

tenant Command

The following example shows the tenant command output:

admin@apic1:~> show tenant infra bridge-domains default
# Executing command: cat /aci/tenants/infra/networking/bridge-domains/default/mo

# bridge-domain

# Naming properties (DO NOT EDIT):
# name                           : default

# Configurable Properties:
description                      :
custom-mac-address               : 00:22:BD:F8:19:FF
l2-unknown-unicast               : hardware-proxy
arp-flooding                     : no
unicast-routing                  : yes
ownerkey                         :
ownertag                         :
network                          : overlay-1
igmp-snoop-policy                :
end-point-retention-policy       :
l3-out                           :
external-route                   :
route-profile                    :
monitoring-policy                :

The following example shows an excerpt of the YAML definition of the tenant command:

- tenant:
help: 'Tenant'
type: alias
dirFormat: '/aci/tenants/'
fileType: 'summary'
name: tenant
sub:
- name: name
label: name
type: arg
modelclass: fv.Tenant
modelprop: name
dirFormat: '/aci/tenants/%(name)s'
fileType: 'summary'
help: Tenant name
sub:
- name: bridge-domains
label: bridge-domains
type: keyword
dirFormat: '/aci/tenants/%(name)s/networking/bridge-domains/'
fileType: 'summary'
help: "All Bridge-domains"
sub:
- name: bd
label: bridge-domain-name
type: arg
modelclass: fv.BD
modelprop: name
dirFormat: '/aci/tenants/%(name)s/networking/bridge-domains/%(b\d)s'
fileType: 'mo'
help: Bridge domain name
- name: application-profiles
label: application-profiles
type: keyword
dirFormat: '/aci/tenants/%(name)s/application-profiles/'
fileType: 'summary'
help: "All application profiles"
sub:
- name: ap
label: application-profile-name
type: arg
modelclass: fv.Ap
modelprop: name
dirFormat: '/aci/tenants/%(name)s/application-profiles/%(ap)s'
fileType: 'mo'
help: Application profile name
- name: private-networks
label: private-networks
type: keyword
dirFormat: '/aci/tenants/%(name)s/networking/private-networks/'
fileType: 'summary'
help: "All private networks"
sub:
- name: pn
label: private-network-name
type: arg
modelclass: fv.Ctx
modelprop: name
dirFormat: '/aci/tenants/%(name)s/networking/private-networks/%\(pn)s'
fileType: 'mo'
help: Private network name
type: arg
modelclass: fv.Ctx
modelprop: name
dirFormat: '/aci/tenants/%(name)s/networking/private-networks/%\(pn)s'
fileType: 'mo'
help: Private network name
(...)

YAML File Format

File Format

You can use the following keywords to define using custom command a .yml file.

- help—A help string that defines the function of the command, argument, or keyword, as follows: help: 'Displays faults for the current path.'

- type—Specifies one of the following command actions:

- alias—Similar to a standard Unix alias command. References a directory in the MIT.

- command—Executes a unix command, such as cat or version.

- showcmd—Executes a show option within a configuration command, such as firmware list.

- dirFormat—Specifies the directory format for the scope. For example, aci/fabric/inventory/pod-1/node-%(id)s specifies a subdirectory for each node.

Note

%(<arg>)s specifies an argument in the dirFormat and cmdFormat strings.

- fileType—Specifies a file type: you can specify summary or mo.

- cmdFormat—Defines the command to execute, as shown in the following example: cmdFormat: 'eventlog' You can specify that a command execute in a specific scope.

- The following options describe command arguments and keywords.

- sub—Defines a sub-scope. Applies only to alias commands.

- name—The name of the argument or keyword.

- label—Defines a label for the argument or keyword.

- type—The sub-command parameter type. arg specifies an argument; keyword specifies a keyword.

- You can use the following options for autocompletion:

- classfilter—Defines a class filter. For example, classfilter: 'fabric.Node.role == "1"' restricts results to MOs that have a role value of 1.

- fill—Enter fill: auto to display child directories for a scope. Applies only to alias commands.

- modelclass—Defines a scope used to autocomplete results.

- modelprop—Defines a property used to autocomplete results, such as name or id.

Chapter 3. Command Reference

This chapter describes the following CLI commands:

- Command Help

- attach

- auditlog

- create

- controller

- diagnostics

- eraseconfig

- eventlog

- faults

- firmware

- health

- loglevel

- man

- mobrowser

- moconfig

- mocreate

- modelete

- mofind

- moprint

- moquery

- moset

- mostats

- password

- reload

- scope

- show

- svcping

- techsupport

- trafficmap

- troubleshoot eptoep session (IP and MAC)

- troubleshoot epext session EP-to-External-IP and External-IP-to-EP

- troubleshoot eptoep session <session name>

- troubleshoot eptoep session <session name> atomiccounter

- troubleshoot eptoep session <session name> traceroute

- troubleshoot eptoep session <session name> traceroute protocol

- troubleshoot eptoep session <session name> traceroute protocol tcp dst port

- show troubleshoot eptoep

- show troubleshoot eptoep session <session name>

- version

- where

Command Help

You can use the following tools to display CLI command help:

- command-name -help—Displays a brief summary of the command.

admin@apic1:aci> controller -h
Usage:  controller [TARGETNODE_ID] [commission|decommission]

Display controller info. Commission or Decommission controllers.

Options:
-h --help

- man command-name—Displays a Linux-style man page for the command.

admin@apic1:aci> man controller

attach

The attach command opens an SSH session to a specified fabric node.

attach apic1

attach leaf1

attach spine1

Example

The following example shows how to use the attach command to connect the leaf1 node:

admin@apic1:aci> attach leaf1
# Executing command: ssh leaf1
Warning: Permanently added 'leaf1,10.0.75.31' (RSA) to the list of known hosts.
admin@leaf1's password:
admin@leaf1:~>

auditlog

An audit log includes auditing information such as login and logout times. To display an audit summary for a given node, module, or interface, use the auditlog command.

auditlog [ auditlog-id]

Syntax Description

auditlog-id

Specifies an audit log number to display.

Example

The following example shows how to use the auditlog command:

admin@apic1:Solar> pwd
/home/admin/aci/tenants/Solar
admin@apic1:Solar> auditlog 4294967305
ID                   : 4294967305
Description          : Tenant Solar created
Affected Object      : uni/tn-Solar
Time Stamp           : 2014-07-21T20:00:25.518+00:00
Cause                : transition
Code                 : E4206326
Severity             : info
Change Set           : name:Solar
Action Performed     : creation
Action Trigger       : config
Transaction ID       : 14411518807585652035
User                 : admin

create

The create command executes a wizard within a given scope; the wizard creates relevant objects in the MIT.

create scope

Example

The following example shows how to use the create command:

admin@apic1:~> create tenant
# Executing command: 'cd /aci/tenants; ./tenant.wiz'

Create Tenant:
--------------
Name             : Cisco
Description      : Cisco Systems
Monitoring Policy:

Security Domains:
-----------------
Name       :
skipping...

Create new network:
-------------------
Name             :
skipping...

Do you want to view the corresponding commands? (Yes/No): Yes
-------------------------------------------------------------------------
mocreate Cisco
pushd .
cd Tenant-Test
moset description "Cisco Systems"

pushd .
cd security-domains
popd

pushd .
cd networking

pushd .
cd private-networks
popd
popd
popd
--------------------------------------------------------------------------------

Do you want to commit changes? (Yes/No): Yes
Adding mo tenants/Cisco
All requests processed successfully!

The tenant section of the create YAML file is defined as follows:

- tenant:
help: 'Tenant'
type: alias
dirFormat: '/aci/tenants/'
fileType: 'summary'
createFile: tenant.wiz
name: tenant

Note

For more information about YAML (.yml) file formats, see Customizing Commands.

controller

To display controller information or to commission or decommission a node, use the controller command.

controller [controller-id] [commission | decommission]

Syntax Description

commission

Commissions (creates) a node.

decommission

Decommissions a specified node.

controller-id

The controller ID.

Example

The following example shows how to use the controller command:

admin@apic1:> controller 1 decommission

diagnostics

To display equipment diagnostic tests, use the diagnostics command.

diagnostics node-id

Syntax Description

node-id

The target node ID or node name. You can specify a range of node IDs or a list of node names.

Example

The following example shows how to use the diagnostics command:

admin@apic1:aci> diagnostics 1
Dn                        Group          Model         Subject Class  Test Set
----------------------------------------------------------------------------------------------
topology/pod-1/node-      internal-conn  N9K-C9396PX   eqptSupC       mgmtp-lb
19/sys/diag/grptests-
eqptSupC-model-[N9K-
C9396PX]-grp-internal-
conn
topology/pod-1/node-      cpu            N9K-C93128TX  eqptSupC       cpu-cache
19/sys/diag/grptests-
eqptSupC-model-[N9K-
C93128TX]-grp-cpu
topology/pod-1/node-      sys-mem        N9K-C93128TX  eqptSupC       bios-mem,mem-health
19/sys/diag/grptests-
eqptSupC-model-[N9K-
C93128TX]-grp-sys-mem
topology/pod-1/node-      peripherals    Nagano        eqptSupC       act2-acc,cons-dev,fpga-
19/sys/diag/grptests-                                                 reg-chk,ge-
eqptSupC-model-                                                       eeprom,nvram-
[Nagano]-grp-                                                         cksum,obfl-acc,spi-
peripherals                                                           cksum,ssd-acc,usb-bus
topology/pod-1/node-      fex            NXS8-4532     eqptLC         extch-fp,extch-
19/sys/diag/grptests-                                                 hp,extch-sprom
eqptLC-model-[NXS8-
4532]-grp-fex

admin@apic1:aci>

eraseconfig

To erase the APIC configuration excluding first-time setup information and reboot the APIC, use the eraseconfig command.

Note

This command causes the APIC to reboot.

Note

This command is removed in APIC Release 1.2(2) and later releases. Use the acidiag touch command followed by a reboot to erase the configuration. See the acidiag command documentation in the Cisco APIC Troubleshooting Guide.

eraseconfig [ setup ]

Syntax Description

setup

Erases first-time setup information. After the reboot, the first-time APIC setup dialog appears on the console.

Example

The following example shows how to use the eraseconfig command:

admin@apic1:~> eraseconfig

eventlog

To display an event summary for a given node, module, or interface, use the eventlog command.

eventlog controller node-id

eventlog switch node-id

eventlog switch interface interface-name node-id

eventlog switch module module-id node-id

eventlog switch module module-id port port-number node-id

Syntax Description

controller

Displays event log for a controller.

switch

Displays event log for a switch.

node-id

The target node ID or node name. You can specify a range of node IDs or a list of node names.

interface

Specifies an interface ID or interface range.

interface-name

The interface ID or range.

module

Specifies a module.

module-id

The module ID.

Example

The following example shows how to use the eventlog command:

admin@apic1:/> eventlog switch 101 interface eth1/1

faults

To display a summary of faults on a given node, module, port, or interface, use the faults command.

faults switch node-id { ack | detail | history | interface interface-name | module module-id port port-number | unack } fault-code

faults controller controller-id { ack | detail | history | unack } fault-code

Syntax Description

controller

Displays health log for a controller.

controller-id

Specifies a controller.

switch

Displays health log for a switch.

node-id

The target node ID or node name. You can specify a range of node IDs or a list of node names.

interface

Specifies an interface ID or interface range.

interface-name

The interface ID or range.

module

Specifies a module.

module-id

The module ID.

detail

Displays fault detail.

ack

Displays acknowledged faults.

unack

Displays unacknowledged faults.

history

Displays historical records.

port

Specifies a port range.

port-number

The port number(s).

fault-code

Specifies a fault code.

Example

The following example shows how to use the faults command:

admin@apic1:faults> faults controller 1 detail

firmware

To manage firmware images in the repository on a fabric controller node, use the firmware command.

Note

This command is provided for local controller software upgrades; you can use policy-driven firmware upgrades to upgrade firmware on fabric controller nodes within a cluster.

firmware add image-name

firmware delete image-name

firmware upgrade status

firmware upgrade status node node-id

firmware upgrade catalog image-name

firmware upgrade controller image-name

firmware upgrade switch node node-id image-name

Syntax Description

add

Adds a firmware image to the repository. You can download the firmware using SCP, FTP, HTTP, or any method for which the user is authorized.

delete

Removes a firmware image from the repository.

image-name

The name of the image file.

list

Lists firmware images in the firmware repository.

upgrade

Upgrades the firmware on a switch or the local APIC.

controller

Specifies a local image installation the controller.

status

Displays the firmware update status.

node-id

The target node ID or node name. You can only install firmware on one node at a time.
Note:
In the case of an APIC, the firmware is installed on all APICs in the cluster.

switch

Specifies an image installation on a switch.

catalog

Upgrades an image within the image catalog.

Example

The following examples show how to use the firmware command:

admin@apic1:~> firmware list
Name                     Type     Major-Version  Minor-Version  Size(Bytes)  Download-Date
-----------------------  -------  -------------  -------------  -----------  ---------------------
ifabric-k9-catalog-      catalog  1.0            (0.566)        7461         2014-01-
1.0.0-566.bin                                                                28T11:17:36.054+00:00

admin@apic1:~> firmware add ifabric-k9-simsw-1.0.0-559.bin
Firmware Image ifabric-k9-simsw-1.0.0-559.bin is added to the repository

admin@apic1:~> firmware list
Name                     Type     Major-Version  Minor-Version  Size(Bytes)  Download-Date
-----------------------  -------  -------------  -------------  -----------  ---------------------
ifabric-k9-catalog-      catalog  1.0            (0.566)        7461         2014-01-
1.0.0-566.bin                                                                28T11:17:36.054+00:00
ifabric-k9-simsw-1.0.0-  switch   1.0            (0.559)        854412177    2014-01-
559.bin

admin@apic1:~> firmware upgrade switch node 17 ifabric-k9-simsw-1.0.0-559.bin
Firmware Installation on Switch Scheduled
To check the upgrade status, use 'firmware upgrade status -t <node-id>'
admin@apic1:~>

admin@apic1:~> firmware upgrade status node 17
Firmware Upgrade Status:
Upgrade-Status  Status  Desired-Version   Install-Stage      Start-Date             End-Date
--------------  ------  ----------------  -----------------  ---------------------  ---------------------
inprogress              simsw-1.0(0.559)  InstallNotStarted  2014-01-               2014-01-
28T11:26:38.313+00:00  28T10:59:37.746+00:00.

admin@apic1:~> firmware upgrade status
Node-Id    Role       Upgrade-Status
--------------------------------------
3          controller notscheduled
17         leaf       completeok
20         spine      notscheduled
1          controller notscheduled
2          controller notscheduled
19         spine      notscheduled
18         leaf       notscheduled

health

To display a health summary of a node, module, interface, or port, use the health command.

health switch node-id { ack | detail | history | interface interface-name | module module-id port port-number | unack }

health controller controller-id { ack | detail | history | unack }

Syntax Description

controller

Displays faults for a controller.

switch

Displays faults for a switch.

node-id

The target node ID or node name. You can specify a range of node IDs or a list of node names.

interface

Specifies an interface or interface range.

interface-name

The interface name or range.

module

Specifies one or more modules by ID.

module-id

The module name.

port

Specifies a port or port range.

port_id

The port number or range.

history

Displays historical records.

Example

The following example shows how to use the health command:

admin@apic1:admin> health switch 101 interface eth1/1
Current Score  Previous Score  Timestamp
-------------  --------------  ---------------------
95             96              2014-07-
21T15:25:24.092+00:00

Total : 1

loglevel

To display the logging settings on the APIC, use the loglevel command.

loglevel get node node-name dme dme-name

loglevel set node node-name dme dme-name topic topic-name severity severity-level

Syntax Description

get

Returns the service log level on a node.

set

Sets the service log level on a node.

node

Specifies a node.

node-name

The node name.

dme

Identifies a service process running on the node.

dme-name

The service process (DME) name. Available DMEs vary by node and include:

- ae

- appliancedirector

- bootmgr

- dbgr

- eventmgr

- nginx

- observer

- policymgr

- scripthandler

- topomgr

- vmmmgr

topic

Specifies a logging subsystem.

topic-name

The logging subsystem.

severity

Specifies a logging severity level.

severity-level

The logging severity level. You can set the following values:

- CRIT—Critical error

- ERROR—Major error

- WARN—Warning

- INFO—Informational error

- DBG4—Debug level 4

- DBG3—Debug level 3

- DBG2—Debug level 2

Example

The following example shows how to use the loglevel command:

admin@apic1:pod-1> loglevel get node spine1 dme dbgrelem
logDefault : DBG4

man

To display the man (manual) page for a command, use the man command.

man command-name

Syntax Description

command-name

The command name.

Example

The following example shows how to use the man command:

admin@apic1> man trafficmap

mobrowser

To launch the managed object (MO) browser, use the mobrowser command.

mobrowser [scope]

Syntax Description

scope

Specifies a scope within the MIT, such as aaa or access.

Example

The following example shows how to use the mobrowser command:

admin@apic1:> mobrowser

moconfig

To commit or discard a configuration stored in the configuration buffer, use the moconfig command.

moconfig { commit | discard | diff | running }

Syntax Description

commit

Commits the configuration stored in the configuration buffer.

discard

Discards the configuration stored in the configuration buffer.

diff

Displays a summary of the difference between the active configuration and the configuration buffer.

running

Shows the CLI commands used to create a configuration for a given context. This option simplifies the process of creating template configurations. For more information about configuration templates, see Creating Configuration Templates.

Example

The following examples show how to use the moconfig command:

admin@apic1:local-users> moconfig diff
--- ./mario/mo  2013-10-01 21:17:06.000000000 -0700
+++ ./mario/mo.buffer   2013-10-01 21:17:53.000000000 -0700
@@ -2,8 +2,8 @@
local-user            :
----------
login-id               : george
-first-name             :
-last-name              :
+first-name             : George
+last-name              : Washington
phone                  :
email                  :
description            :

admin@apic1:local-users> moconfig commit
Commit Successful
admin@apic1:local-users> moconfig diff
admin@apic1:local-users>

admin@apic1:aci > cd tenants/
admin@apic1:tenants> moconfig running
cd /aci/viewfw/tenants
cd networking
mocreate fv-tenant-common
moconfig commit
mocreate fv-tenant-test
moconfig commit
mocreate fv-tenant-mgmt
moconfig commit
cd external-routed-networks
mocreate l3ext-out-x
moconfig commit
mocreate l3-outside-x
moconfig commit
cd l3-outside-x
cd logical-node-profiles
mocreate nodex
cd nodex
moset tag yellow-green
moconfig commit

mocreate

To create a managed object (MO), use the mocreate command.

Note

If you do not specify a scope, the command creates an MO in the current context.

mocreate [context] name property-name property-value

Syntax Description

context

The context for the MO.

name

(Optional) The MO name.

property-name

(Optional) Specifies a property of the MO.

property-value

(Optional) Specifies a value for the property.

Example

The following example shows how to use the mocreate command to create an MO representing a user:

admin@apic1:node-associations> mocreate LS-all/
admin@apic1:node-associations> moconfig commit
Committed mo 'fabric/policies/fabric-policy-associations/leaf/node/LNP/node-associations/LS-all'
All mos committed successfully.
admin@apic1:node-associations> ls
LS-all

To override default settings, you can specify additional properties with the mocreate command, as shown in the following example.

admin@apic1:private-networks> pwd
/aci/tenants/common/networking/private-networks
admin@apic1:private-networks> mocreate Private1 monitoring-policy Monitor1

modelete

To remove a managed object (MO), use the modelete command.

Note

This command is typically used to remove a lower-level scope.

modelete mo-name

Syntax Description

mo-name

The directory name containing the MO.

Example

admin@apic1:node-associations> modelete LS-all/

mofind

To search for a selected MO within the management information tree (MIT), use the mofind command.

mofind scope class package.class mo-value

Syntax Description

class

Class argument; specifies a class of MO to return

package

The name of the MO package.

class

The name of the MO class

mo-value

The MO name

Example

The following example shows how to use the mofind command:

admin@apic1:aci> mofind . class fv.Tenant /.aci/viewfs/tenants/t14/mo
/.aci/viewfs/tenants/infra/mo
/.aci/viewfs/tenants/common/mo
/.aci/viewfs/tenants/Solar/mo
/.aci/viewfs/tenants/mgmt/mo

admin@apic1:aci> mofind . class aaa.User /.aci/mitfs/uni/userext/user-admin/mo
/.aci/viewfs/admin/aaa/security-management/local-users/admin/mo

moprint

To specify an output format for managed objects and managed object buffer files, use the moprint command.

Note

This command is useful for automation because it provides standardized output.

moprint { exclude-help | include-help } { json | pretty | xml }

Syntax Description

exclude-help

Specifies that the output omit property descriptions

include-help

Specifies that the output contain property descriptions

json

Specifies JSON output

pretty

Specifies XML output in a tabular format

xml

Specifies XML output

Example

The following example shows how to use the moprint command to provide JSON output displaying MO properties:

admin@apic1:local-users> moprint json
admin@apic1:local-users> cat ./mario/mo
{
"aaaUser": {
"attributes": {
"aaaUserclearPwdHistory": {
"value": "no"
},
"aaaUseremail": {
"value": ""
},
"aaaUserlastName": {
"value": "Washington"
},
"aaaUserphone": {
"value": ""
},
"aaaUserdescr": {
"value": ""
},
"aaaUserexpiration": {
"value": "never"
},
"aaaUserexpires": {
"value": "no"
},
"aaaUserencPwd": {
"value": ""
},
"aaaUseraccountStatus": {
"value": "active"
},
"aaaUsername": {
"value": "george"
},
"aaaUserfirstName": {
"value": "George"
},
"aaaUserpwdLifeTime": {
"value": "no-password-expiration"
},
"aaaUserpwd": {
"value": ""
}
}
}
}

moquery

To run a query for a managed object (MO), use the moquery command.

moquery { --help | --host host-id | --port portname | --dn dn | --klass classname | --filter property | --attrs attributes | --output output | -user username | --options options }

Syntax Description

--help or –h

Specifies an APIC host.

--host or –i

Specifies an APIC host.

host-id

The host name or IP address of an APIC.

--port or –p

Specifies a port for a REST interface.

portname

The REST interface port number.

--dn or –d

Specifies a distinguished name (DN) for a managed object (MO).

dn

The DN of an MO.

--klass or –c

Specifies a class name for the query.

classname

Specifies a class. You can enter multiple classes separated by commas.

--filter or –f

Specifies a property on which to filter MOs.

property

The property on which to filter MOs.

--attrs or –a

Specifies the attributes that the query displays.

attributes

The type of attributes to display. You can choose config (configuration attributes) or all. If config is selected, only configurable attributes are displayed. Unless the table output format is specified, the default is all.

--output or –o

Specifies a query output format.

output

The query output format. You can choose json, xml, block, or table.

--user or –u

Specifies a user name.

username

The user name.

--options or –x

Specifies query options.

options

The query options to enable. For more information, see Usage Guidelines.

Usage Guidelines

Using --options (or –x), you can specify query options as supported by the REST API. You can add multiple options statements to the command, using syntax such as the following:

-x [OPTIONS [OPTIONS ...]] [-x [OPTIONS [OPTIONS ...]]]

For example:

moquery -c firmwareCtrlrFwStatusCont -x query-target=subtree target-subtree-class=firmwareCtrlrRunning

Example

The following example shows how to use the moquery command:

admin@apic1:~> moquery --dn unallocencap-[uni/infra]
Total Objects shown: 1

# stp.UnAllocEncapCont
infraPKey    : uni/infra
allocSize    : 0
childAction  :
descr        :
dn           : unallocencap-[uni/infra]
lastAssigned : 8192
lcOwn        : local
modTs        : 2014-07-26T16:46:27.176+00:00
name         :
ownerKey     :
ownerTag     :
rn           : unallocencap-[uni/infra]
size         : 0
status       :

moset

To set the properties for a managed object (MO), use the moset command.

moset { property-name property-value [add | remove ] }

Syntax Description

property-name

Property name

property-value

Property value

add

Adds a property to the managed object

remove

Removes a property from the managed object

Example

The following example shows how to use the moset command to set the properties of a managed object:

admin@apic0:local-users> cat george/mo
# aaa.User
local-user            :
----------
login-id               : george
first-name             :
last-name              :
phone                  :
email                  :
description            :
account-status         : active
account-expires        : no
expiration-date        : never
clear-password-history : no
encrypted-password     :
password               :
password-life-time     : no-password-expiration
admin@apic0:local-users> moset first-name George last-name Washington
admin@apic0:local-users> cat mario/mo.buffer
# aaa.User
local-user            :
----------
login-id               : george
first-name             : George
last-name              : Washington
phone                  :
email                  :
description            :
account-status         : active
account-expires        : no
expiration-date        : never
clear-password-history : no
encrypted-password     :
password               :
password-life-time     : no-password-expiration
admin@ifc0:local-users>

mostats

To display statistics for a MO, use the mostats command.

mostats [stats-class] [sampling-interval interval] [location location-name] [counter counter-name] [values values-name] [from date-from] [to date-to] [thresholded thresholded-flags] [output-to outputname]

Syntax Description

stats-class

Statistics type; use Tab autocomplete to display a list of available statistics in the current scope

sampling-interval

Specifies a sampling interval for the statistic

interval

Sampling interval; you can choose the following values:

- 5min

- 15min

- 1h

- 1d

- 1w

- 1mo

- 1qtr

- 1year

5 minutes is the default value

location

Specifies a location from which to display statistics

location-name

Location from which to display statistics; you can chose history or current

counter

Specifies a specific counter to display. If you omit this keyword, the command displays all counters.

counter-name

Counter name. If you do not specify a counter name, the command displays the value of all counters.

You can use autocomplete to display a list of available counters.

values

Specifies specific values to display

values-name

Type of values to display. You can use autocomplete to display a list of available values.

Note:   Statistics values vary according to the specified counter and location.

from

Specifies a start date and time for statistics. This keyword is used for historical statistics.

date-from

Start date for the query

to

Specifies an end date and time for statistics. This keyword is used for historical statistics.

date-to

End date for the query

thresholded

Specifies historical statistics that have crossed exceeded a threshold value

thresholded-flags

The threshold flag value

output-to

Specifies a specific output type

output-name

Output type; you can choose the following values:

- table

- graph

Example

The following example shows how to use the mostats command:

admin@apic0:leafport-17> mostats ingress-byte-counters location history
Counters:
flood (bytes) : periodic value
multicastRate (bytes-per-second) : average value
multicast (bytes) : periodic value
unicastRate (bytes-per-second) : average value
unicast (bytes) : periodic value

Time Interval            flood     multicastRate  multicast   unicastRate   unicast
2013-10-23 13:40:10 + 300sec  1692622494     6038011     1811403699    5959938    1787981697
2013-10-23 13:45:10 + 290sec  1701770043     5896513     1709988944    6350713    1841707150
2013-10-23 13:50:00 + 300sec  1875699742     6327240     1898172394    5204047    1561214263
2013-10-23 13:55:00 + 300sec  1991025635     6407343     1922203057    5961950    1788585183
2013-10-23 14:00:00 + 310sec  2020555778     6857403     2125795303    7152710    2217340307
2013-10-23 14:05:10 + 290sec  1884001802     6545303     1898138103    5878862    1704870238
2013-10-23 14:10:00 + 310sec  2037567241     5880848     1823063295    6927670    2147577849
2013-10-23 14:15:10 + 300sec  1651084097     6128338     1838501627    5696007    1708802494
2013-10-23 14:20:10 + 300sec  2119253728     5719718     1715322961    5606184    1681939173
2013-10-23 14:25:10 + 300sec  1824918785     6553074     1965922597    6167935    1850380704
2013-10-23 14:30:10 + 300sec  1794072506     6508516     1952555134    6745063    2023519193
2013-10-23 14:35:10 + 290sec  2305467846     6493923     1883237807    6693507    1941117370

password

To change the password on the APIC , use the password command.

password

Example

The following example shows how to use the password command:

admin@apic1:aci> passwd
Changing password for user admin.
(current) password:
New password:
Retype new password:
Password for user admin is changed successfully.
admin@apic1:aci>

reload

To reload a specified node or module, use the reload command.

Note

If you do not specify a node, the command reloads the node in the current context.

reload { controller | switch } node-id

Syntax Description

controller

Reloads a controller

switch

Reloads a switch

node-id

The target node ID or node name. You can specify a range of node IDs or a list of node names.

Example

The following example shows how to use the reload command:

admin@apic1:aci> reload switch 118

scope

To jump to the directory for a scope, use the scope command.

Note

The where command displays the MIT directory for a context, while scope opens the directory.

scope scope-name

Syntax Description

scope-name

The scope name, such as aaa or access-policies

Example

The following examples show how to use the scope command:

admin@apic1:~> pwd
/home/admin
admin@apic1:/> scope tenant
Changing directory to /.aci/tenants/
admin@apic1:tenants> pwd
/aci/tenants

show

The show command displays the APIC configuration in a format similar to Cisco IOS and NX-OS. The command is similar to the alias Linux command.

show context

Syntax Description

context

The context name, such as aaa or access-policies

Contexts

The following example shows the standard show options:

admin@apic1:~> show <Esc><Esc>
aaa                       aaa
access                    Fabric Access Policies
auditlog                  Show auditlog on current path
bgp                       Show BGP information
cdp                       Show Cisco Discovery Protocol information
controller                Controller Node
cores                     cores
eventlog                  Show eventlog on current path
external-data-collectors  external-data-collectors
fabric                    Fabric Details
faults                    Show faults current path
fex                       Show fex information
firmware                  Show firmware
health                    Show health on current path
historical-record-policy  historic-record-policies
import-export             Import/Export
interface                 Show interface status and information
interface-policies        interface-policies
ip                        Display IP information
isis                      Display IS-IS status and configuration
l4-l7                     L4-L7 Sevices Details
lldp                      Show information about lldp
module                    Show module information
schedulers                schedulers
switch                    Switch Node
tenant                    Tenant
trafficmap                Show trafficmap
version                   Show version
vmware                    VMware vCenter/vShield Controllers
vpc                       Show vpc information

Customizing the show Command

You can customize the show command with a simple YAML (.yml) configuration. For examples, see the .yml files in the /etc/scopedefs directory.

You can define custom show commands by creating a .yml file in your /home/username/scopedefs/ directory. You can ignore specific show scopes by adding them to the /home/username/scopedefs/.ignore.yml file.

You can also define custom show commands that execute at that specific scope, as shown in the cmdFormat value in the following example:

vmware :
type: alias
help: "VMware vCenter/vShield Controllers"
name: vmware
label: vmware
sub:
- name: controllers
label: controllers
type: keyword
cmdFormat: "find /aci/vm-networking/inventory/VMware/vmm-domains/ -name controllers -exec echo ';' -exec echo {} ';' -exec cat '{}/summary' ';'"
help: "Status of all Controllers"
- name: domain
label: domain
type: keyword
help: "Domain"

Note

For more information about YAML (.yml) file formats, see Customizing Commands.

Example

The following example shows how to use show to view local users.

admin@apic1:~> show aaa local-users
# Executing command: cat /aci/admin/aaa/security-management/local-users/summary

local-users:
login-id  first-name  last-name  email  phone
--------  ----------  ---------  -----  -----
admin

The following excerpt shows the YAML definition for the aaa scope of the show command.

- aaa:
name: aaa
help: 'aaa'
type: alias
dirFormat: ' '
sub:
- name: local-users
label: local-users
type: keyword
dirFormat: '/aci/admin/aaa/security-management/local-users/'
fileType: 'summary'
help: 'local users'

svcping

To ping the management interface of a service device, use the svcping command.

Note

This command is supported within the Management Information Tree file system (mit); the command is not supported within the aci file system.

svcping path

Syntax Description

path

The path of the service device (CDev) within the mit file system

techsupport

To display troubleshooting information, use the techsupport command.

techsupport all { [status] | [remotename fname ] }

techsupport controllers [status]

techsupport controllers remotename fname

techsupport db svc svcname [delete]

techsupport local

techsupport remote { list | name} [ fname ] {delete | [ {host remoteport protocol username password remotepath } ] }

techsupport switch nodeid { [status] | [remotename fname ] }

Syntax Description

all

Displays tech support information for all nodes in the ACI fabric

controllers

Displays faults for fabric controllers

db

Collects a snapshot of database information.

delete

Removes a tech support file

fname

The name of the remote destination

host

The remote host name

list

Lists all remote destinations

local

Collects tech support information locally

name

Specifies a remote destination

node-id

The target node ID or node name. You can specify a range of node IDs or a list of node names.

remote

Lists, adds, or deletes remote destinations for tech support information

remotename

The name of a remote destination

remotepath

The path to the remote destination

remoteport

The remote port number

password

The passport for the remote destination

protocol

The protocol for the remote destination

status

Status of the tech support output

svc

Specifies a service

svcname

The service name

switch

Displays faults for a switch

username

The username for the remote destination

The techsupport command exports a file containing information about the current state of the ACI fabric or nodes. This information is very helpful to Cisco support and frequently provides the information needed to identify the source of a problem. The file is exported to the specified remote destination.

Beginning in Cisco APIC Release 1.1, three files are created and exported by this command:

- filename.tar.gz—Contains configuration files, faults, events, debug counters, and other system information.

- filename_db.tar.gz—Contains databases (.db files) collected from the node, one for each shard and replica.

- filename_logs.tar.gz—Contains all logs collected from the node. For a switch node, the NX-OS techsupport data is included in this file.

Example

The following example shows how to use the techsupport command in releases earlier than Cisco APIC Release 1.1.

admin@apic1:~> techsupport switch 101
Triggering techsupport for Switch 101 using policy supNode101
Triggered on demand tech support successfully for node 101, will be available at: /data/techsupport on the controller.
Use 'status' option with your command to check techsupport status

trafficmap

To display a summary of traffic between two nodes, use the trafficmap command.

controller srcnode source-node-id destnode dest-node-id

Syntax Description

srcnode

Specifies a node name

source-node-id

The source node name

destnode

Specifies a destination node

dest-node-id

The destination node name

Example

The following example shows how to use the trafficmap command:

admin@apic1:> trafficmap srcnode 102 destnode 112

troubleshoot eptoep session (IP and MAC)

To create an IP troubleshooting session, use the troubleshoot eptoep session <session_name> srcip <src_ip> tenant <src_tenant> app <src_app> epg <src_epg> destip <dest_ip> tenant <dest_tenant> app <dest_app> epg <dest_epg> command.

To create a MAC troubleshooting session, use the troubleshoot eptoep session <session_name> srcmac <src_mac> tenant <src_tenant> app <src_app> epg <src_epg> destmac <dest_mac> tenant <dest_tenant> app <dest_app> epg <dest_epg> command.

Once the session is created, the following configuration options are available:

- atomiccounter start

- atomiccounter stop

- traceroute start

- traceroute stop

- traceroute protocol <prot> dstport <dst_port>

- report [<format>]

- delete

- description <descr>

- latestminutes <num_min>

- starttime <start_time> endtime <end_time>

- monitor destination tenant <tenant_name> application <appln> epg <epg_name> ip_addr <ip_address> srcipprefix <ip_prefix> [(flowid <flow_id>)]

- monitor stop

- scheduler <scheduler-name>

- scheduler delete

Examples

The following example shows how to create the IP troubleshoot eptoep session session:

admin@apic1:/> troubleshoot eptoep session <session_name> srcip <src_ip> tenant <src_tenant> app <src_app> epg <src_epg> destip <dest_ip> tenant <dest_tenant> app <dest_app> epg <dest_epg>

The following example shows how to create the MAC troubleshoot eptoep session session:

admin@apic1:/> troubleshoot eptoep session <session_name> srcmac <src_mac> tenant <src_tenant> app <src_app> epg <src_epg> destmac <dest_mac> tenant <dest_tenant> app <dest_app> epg <dest_epg>

troubleshoot epext session EP-to-External-IP and External-IP-to-EP

To create an EP to external IP troubleshooting session, use the troubleshoot epext session <session_name> srcip <src_ip> tenant <src_tenant> app <src_app> epg <src_epg> destextip <dest_ip> command.

To create an external IP to EP troubleshooting session, use the troubleshoot epext session <session_name> srcextip <src_ip> destip <dest_ip> tenant <dest_tenant> app <dest_app> epg <dest_epg> command.

Once the session is created, the following configuration options are available:

- atomiccounter start

- atomiccounter stop

- traceroute start

- traceroute stop

- traceroute protocol <prot> dstport <dst_port>

- report [<format>]

- delete

- description <descr>

- latestminutes <num_min>

- starttime <start_time> endtime <end_time>

- monitor destination tenant <tenant_name> application <appln> epg <epg_name> ip_addr <ip_address> srcipprefix <ip_prefix> [(flowid <flow_id>)]

- monitor stop

- scheduler <scheduler-name>

- scheduler delete

Examples

The following example shows how to create the external IP troubleshoot epext session session:

admin@apic1:/> troubleshoot epext session <session_name> srcextip <src_ip> destip <dest_ip> tenant <dest_tenant> app <dest_app> epg <dest_epg>

troubleshoot eptoep session <session name>

To schedule a troubleshooting session, use the schedule troubleshoot eptoep session <session name>option command.

Syntax Description

atomiccounter

Configure atomic counter between the source and destination end-points

delete

Delete this troubleshoot session

description

Textual description of this troubleshooting session

latestminutes

Enter time window in number of minutes from current time

monitor

Configure monitor session to span the source and destination interfaces

report

Generate troubleshooting report

scheduler

Configure a scheduler for this session

srcip

Configure source endpoint IP

srcmac

Configure source endpoint MAC

starttime

Time when the problem started

traceroute

Configure traceroute session between two endpoints

Example

The following example shows how to use the troubleshoot eptoep session <session name> command:

admin@apic1:/> troubleshoot eptoep session <session name>report

troubleshoot eptoep session <session name> atomiccounter

To configure a new endpoint (ep) to endpoint atomic counter session, use the troubleshoot eptoep session newSession atomiccounteroption command.

Syntax Description

start

Start atomiccounter session

stop

Stop atomiccounter session

Example

The following example shows how to use the troubleshoot eptoep session <session name> atomiccounter command:

admin@apic1:/> troubleshoot eptoep session <session name> atomiccounter start

troubleshoot eptoep session <session name> traceroute

To configure a new endpoint (ep) to endpoint traceroute session, use the troubleshoot eptoep session <session name> tracerouteoption command.

Syntax Description

protocol

Configure traceroute protocol

start

Start traceroute policy

stop

Stop traceroute policy

Example

The following example shows how to use the troubleshoot eptoep session <session name> traceroute command:

admin@apic1:/> troubleshoot eptoep session <session name> traceroute start

troubleshoot eptoep session <session name> traceroute protocol

To configure a new endpoint (ep) to endpoint traceroute protocol session, use the troubleshoot eptoep session <session name> traceroute protocoloption command.

Syntax Description

<prot>

Specify IP protocol (tcp|udp|icmp)

Example

The following example shows how to use the troubleshoot eptoep session <session name> traceroute protocol command:

admin@apic1:/> troubleshoot eptoep session <session name> traceroute protocol icmp

troubleshoot eptoep session <session name> traceroute protocol tcp dst port

To configure a new endpoint (ep) to endpoint traceroute protocol session, use the troubleshoot eptoep session <session name> traceroute protocol tcpoption command.

Syntax Description

<dstport>

Specify destination L4 port to be used by traceroute

Example

The following example shows how to use the troubleshoot eptoep session <session name> traceroute protocol command:

admin@apic1:/> troubleshoot eptoep session <session name> traceroute protocol tcp dstport 80

show troubleshoot eptoep

To show an endpoint (ep) to endpoint connection, use the show troubleshoot eptoepoption command.

Syntax Description

session

Show session information

sessions

Show all session names

Example

The following example shows how to use the show troubleshoot eptoep command:

admin@apic1:/> show troubleshoot eptoep

show troubleshoot eptoep session <session name>

To show an endpoint (ep) to endpoint MAC session, use the show troubleshoot eptoep session <session name>option command.

Syntax Description

atomiccounter

Show atomic counters

audit

Show audit information

contracts

Show contract information

deployments

Show deployment changes

events

Show events

faults

Show faults

monitor

Show monitor status

reports

Show reports

statistics

Show statistics

topology

Show topology

traceroute

Show traceroute results

Example

The following example shows how to use the show troubleshoot eptoep session <session name> command:

admin@apic1:/> show troubleshoot eptoep session <session name>

version

To display the current software version of a node, use the version command.

Note

If you do not specify a node, the command displays the current software version of all configured nodes.

version { controller | switch } [node-id ]

Syntax Description

controller

Displays the version for a controller

switch

Displays the version for a switch

node-id

The target node ID or node name. You can specify a range of node IDs or a list of node names.

Example

The following examples show how to use the version command:

admin@apic1:~> version switch 101
node type  node id  node name  version
---------  -------  ---------  ----------------
leaf       101      leaf1      simsw-1.0(0.450)

admin@apic1:~> version
node type   node id  node name  version
----------  -------  ---------  ----------------
controller  1        apic1      1.0(0.450)
controller  2        apic2      1.0(0.450)
controller  3        apic3      1.0(0.450)
leaf        101      leaf1      simsw-1.0(0.450)
leaf        102      leaf2      simsw-1.0(0.450)
leaf        103      leaf3      simsw-1.0(0.450)
spine       104      spine1     simsw-1.0(0.450)
spine       105      spine2     simsw-1.0(0.450)

where

To display the management information tree (MIT) directory path for a scope, use the where command.

where scope-name

Syntax Description

scope-name

The scope name, such as aaa or access-policies.

Example

The following examples show how to use the where command:

admin@apic1:~> where aaa local-users admin
/aci/admin/aaa/security-management/local-users/admin

Preface

This preface includes the following sections:

- Audience

- Document Conventions

- Related Documentation

- Documentation Feedback

Audience

This guide is intended for network and systems administrators who configure and maintain the Application Centric Infrastructure fabric.

Document Conventions

Command descriptions use the following conventions:

Convention

Description

bold

Bold text indicates the commands and keywords that you enter literally as shown.

Italic

Italic text indicates arguments for which the user supplies the values.

[x]

Square brackets enclose an optional element (keyword or argument).

[x | y]

Square brackets enclosing keywords or arguments separated by a vertical bar indicate an optional choice.

{x | y}

Braces enclosing keywords or arguments separated by a vertical bar indicate a required choice.

[x {y | z}]

Nested set of square brackets or braces indicate optional or required choices within optional or required elements. Braces and a vertical bar within square brackets indicate a required choice within an optional element.

variable

Indicates a variable for which you supply values, in context where italics cannot be used.

string

A nonquoted set of characters. Do not use quotation marks around the string or the string will include the quotation marks.

Examples use the following conventions:

Convention

Description

screen font

Terminal sessions and information the switch displays are in screen font.

boldface screen font

Information you must enter is in boldface screen font.

italic screen font

Arguments for which you supply values are in italic screen font.

< >

Nonprinting characters, such as passwords, are in angle brackets.

[ ]

Default responses to system prompts are in square brackets.

!, #

An exclamation point (!) or a pound sign (#) at the beginning of a line of code indicates a comment line.

This document uses the following conventions:

Note

Means reader take note. Notes contain helpful suggestions or references to material not covered in the manual.

Caution

Means reader be careful. In this situation, you might do something that could result in equipment damage or loss of data.

Warning

IMPORTANT SAFETY INSTRUCTIONS

This warning symbol means danger. You are in a situation that could cause bodily injury. Before you work on any equipment, be aware of the hazards involved with electrical circuitry and be familiar with standard practices for preventing accidents. Use the statement number provided at the end of each warning to locate its translation in the translated safety warnings that accompanied this device.

SAVE THESE INSTRUCTIONS

Related Documentation

Cisco Application Centric Infrastructure (ACI) Documentation

The ACI documentation is available at the following URL: Click Here .

Cisco Application Centric Infrastructure (ACI) Simulator Documentation

The Cisco ACI Simulator documentation is available at Click Here .

Cisco Nexus 9000 Series Switches Documentation

The Cisco Nexus 9000 Series Switches documentation is available at Click Here .

Cisco Application Virtual Switch Documentation

The Cisco Application Virtual Switch (AVS) documentation is available at Click Here .

Cisco Application Centric Infrastructure (ACI) Integration with OpenStack Documentation

Cisco ACI integration with OpenStack documentation is available at Click Here .

Documentation Feedback

To provide technical feedback on this document, or to report an error or omission, please send your comments to apic-docfeedback@cisco.com. We appreciate your feedback.