> For the complete documentation index, see [llms.txt](https://nso-docs.cisco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nso-docs.cisco.com/neds/cisco-provided-neds/cisco-apicdc/readme-ned-settings.md). # README-ned-settings ## NED settings details *** This NED is equipped with a number of runtime configuration options "NED settings" allowing for customization by the end user. All options are configurable using the NSO API for NED settings. Most NED settings can be configured globally, per device profile or per device instance in the following locations: global /ncs:devices/global-settings/ned-settings/cisco-apicdc/ profile /ncs:devices/ncs:profiles/profile:/ned-settings/cisco-apicdc/ device /ncs\:/device/devices/device:/ned-settings/cisco-apicdc/ Profiles setting overrides global-settings and device settings override profile settings, hence the narrowest scope of the setting is used by the device. If user changes a ned-setting, then user must reconnect to the device, i.e. disconnect and connect in order for the new setting to take effect. From the NSO CLI the device instance NED settings for this NED are available under: ``` # config # devices device dev-1 ned-settings cisco-apicdc Press TAB to see all the NED settings. ``` ## Table of contents *** ``` 1. ned-settings cisco-apicdc 2. logger 3. alternative-hosts 4. nso-controlled-dns-list 5. deviceBehaviourWorkaround 6. ssl 7. live-status 8. connection ``` ## 1. ned-settings cisco-apicdc *** ``` - sync-from-file-enable (default false) If this is enabled, then NO apic config export will be triggered at sync-from; The config file would need to be placed manually at the location defined by: config-path and sync-from-fileName; Use this when the same static config needs to be loaded on multiple NEDs - sync-from-fileName Config file name used if sync-from-file-enable == true; This is used together with config-path to define the location of config file; - sync-from-dump-enable (default false) Set to TRUE to enable dumping the final config into a local file. The file name is 'current time'.xml, a new file is created afte each sync-from - config-path Specify the directory for configuration;. - local-host (default true) If true the config file will be stored on localhost. In this case please note that the user under which NSO is running must have read/write access to the folder described by 'ned-settings cisco-apicdc config-path' If false then, the , , , and fields are in the context of the remote - host Specify the host;. - ned-to-file-host-authentication-type (default password) Specifies the authentication method the NED uses to connect to the configuration dump host. password - username and password authentication, 'user-name' and 'user-password' are used. shared-key - pre-shared key, 'user-name', 'private-key-path' and 'private-key-passphrase' are used, use PEM format: ssh-keygen -t rsa -b 3072 -m PEM. - user-name Specify the user name;. - user-password Specify the user password;. - ned-to-file-host-private-key-path Local filesystem path to the private key file. - ned-to-file-host-private-key-passphrase Passphrase for the private key, if protected. - port (default 22) Port number. scp,sftp:22, ftp:21. - protocol (default sftp) ftp, sftp or scp; The APIC-DC device will use to copy the config archive on the remote host and the NED will use to get that config archive; So please note that, the remote host needs to support . In case of scp you need to set ned-settings/cisco-apicdc/local-host=true ftp - ftp. sftp - sftp. scp - scp. - apic-to-file-host-authentication-type (default password) Specifies the authentication method the APIC uses to connect to the configuration dump host. password - username and password authentication, 'user-name' and 'user-password' are used. shared-key - pre-shared key, 'user-name', 'private-key-path' and 'private-key-passphrase' are used, use PEM format: ssh-keygen -t rsa -b 3072 -m PEM. - apic-to-file-host-user-name username for the APIC -> HOST file transfer. Leave empty if you want to use the common 'user-name' field (original behavior). - apic-to-file-host-user-password password for APIC -> HOST if 'apic-to-file-host-user-name' is specified and you're not using shared key login. - apic-to-file-host-private-key-path Local filesystem path to the private key file. - apic-to-file-host-private-key-passphrase Passphrase for the private key, if protected. - apic-to-file-host-port (default 22) APIC -> HOST port number. scp,sftp:22, ftp:21. - apic-to-file-host-protocol (default sftp) ftp, sftp or scp; The APIC-DC device will use or to copy the config archive on the remote host. ftp - ftp. sftp - sftp. scp - scp. - management-EPG Management EPG in or out of band, do not set if not using management EPG. If set, adds or to the http body when setting the remove location used for configuration export. POST /api/node/mo/.xml in-band - in-band. out-of-band - out-of-band. - cfgDownloadTimeout (default 1200) This timeout is used to trigger an exception when downloading the APIC configuration archive takes too much; Default 1200[s] -> 20 min; Set 0[s] to disable --> NOT ADVISABLE; if local-host == true Exception is triggered if: (localDownloadComplete - localDownloadStart) > cfgDownloadTimeout; if local-host == false there are two downloads of the cfg file: a) APIC -- > remote host; b) remote host --> NED; In both a) and b) cfg-download-timeout is used. - commit-fully-fit-only (default false) Set this field to enable if you want to enable the following health check: APIC has a field, "health" field, to indicate its health state if APIC is available to accept the configuration changes/updates. If the field shows "fully-fit", that means the APIC is available to use for normal operation. If the field shows any other state, that means we can't use the APIC. If the "health" field on the APIC shows other state than "fully-fit" the NED needs to inspect another alternative host (if configured) and check it is available to use. - disable-check-sync (default false) When set to true, check-sync function will be disabled and commits will be accepted even if the ned is out of sync with the device; Used to speed up the commit procedure when the check sync feature is not mandatory. - check-sync-filter This list is used to define operational data objects that will be filtered out when computing the check-sync operation. Example: check-sync-filter licenseFeatureCont ... will be filtered out when performing the check-sync operation - dataTransferTimeOut (default 0) This time-out value will affect the REST operations; This will change the default socket timeout (SO_TIMEOUT) in milliseconds which is the timeout for waiting for data; A timeout value of zero is interpreted as an infinite timeout; The default value is 0: wait forever; - ignore-passwords (default false) If this is false (default), the NED will read the password fields(from the config) from NSO configuration database when executing sync-from and compare-config. This is used to avoid compare config diffs, when de APIC device will return hashed passwords in the configuration that are changing at each configuration export. If this is true the NED will ignore the password fields that are coming from the APIC device. ``` ## 2. ned-settings cisco-apicdc logger *** Settings for controlling logs generated. ``` - logger level (default info) Set level of logging. error - error. info - info. verbose - verbose. debug - debug. - logger java (default true) Toggle logs to be added to ncs-java-vm.log. ``` ## 3. ned-settings cisco-apicdc alternative-hosts *** Alternative Ip address or host name for the APIC cluster. The NED has the ability to connect to alternative devices in the APIC cluster if the main APIC is down. If the connection fails to the main APIC the NED will try one by one the hosts in the alternative-hosts list. ``` - alternative-hosts - hosts ``` ## 4. ned-settings cisco-apicdc nso-controlled-dns-list *** List of objects controlled by NSO; The list is used to limit the amount of configuration data exported from APIC; Only the dn:s in the list will be considered by the check-sync and sync-from functions This allows to have APIC configuration to be split into NSO controlled and not NSO controlled items If the list is empty, the complete APIC config will be used in check-sync and sync-from Items in the list shall be in dn format Example: \[uni/tn-aTenant uni/infra uni/l3dom-aL3Domain ]; The objects in the list must be direct under uni Objects further down in the tree is not possible to specify in this list. ``` - nso-controlled-dns-list - dns ``` ## 5. ned-settings cisco-apicdc deviceBehaviourWorkaround *** This ned settings enable custom behaviours needed for some unexpected device behaviour. ``` - deviceBehaviourWorkaround enable-l3extOut-cfg-split (default false) Added in ticket (APIC-218 / PS-39134 / RT44030). The issue we’re facing is as follows: - If we try and push both the l3-outs at the sametime, I get an error Payload: - Error: - If I push just a single l3extOut, it succeeds. The second subsequent fails. - If I push all L3ExtOut related configuration first for a single object and then commit the second, it succeeds. E.g. push all configurations related to Gaming-RDC-3_SRL3out first and then the second L3outExt 5BGaming-CDC-2_SRL3out, it works. - Solution: a patch that splits out the l3extOut configuration. To push the config for l3extOut one by one (create one l3extOut with all the children config and repeat). Of course this will greatly slows down the config operation, and this is why this is not in the main version of the apic NED. ``` ## 6. ned-settings cisco-apicdc ssl *** Use SSL for connections towards the device. ``` - ssl accept-any (default true) Accept any SSL certificate presented by the device. Warning! This enables Man in the Middle attacks and should only be used for testing and troubleshooting. - ssl certificate SSL certificate stored in DER format but since it is entered as Base64 it is very similar to PEM but without banners like. Default uses the default trusted certificates installed in Java JVM. An easy way to get the PEM of a server: openssl s_client -connect HOST:PORT ``` ## 7. ned-settings cisco-apicdc live-status *** Configure NED settings related to live-status. ``` - live-status time-to-live (default 50) Define time-to-live for data fetched from the device via live-status.(default 50). ``` ## 8. ned-settings cisco-apicdc connection *** Configure settings specific to the connection between NED and intermediary config upload device. ``` - connection ssh client (default ganymed) Specifies the SSH client used for device connectivity. The NED automatically detects the appropriate default based on the installed NSO version: Ganymed is the default for legacy versions, SSHJ for NSO 6.x versions, and the Apache MINA-based client is the default for NSO 6.8 and later. This auto-detection is overridden if this leaf is explicitly configured. ganymed - Legacy SSH client. Deprecated; may be required for older devices with restricted cipher support. sshj - SSHJ-based client. Supports most modern cryptographic standards. mina - Apache MINA-based client. Supports the latest cryptographic standards, including PQC algorithms. ``` ## 9. Details regarding the added authentication options for the sync-from file transfer. *** During sync-from the configuration archive is transferred in two independent hops: APIC -> HOST (the APIC exports the archive to an intermediary file server) and NED -> HOST (the NED pulls that archive back from the same host). Each hop can use its own credentials, port, protocol and authentication method (username/password or SSH pre-shared key). All private-key paths are locations on the local NSO filesystem, even for the APIC hop: the NED reads the key file and forwards its contents to the APIC. Keys must be in PEM format: ``` ssh-keygen -t rsa -b 3072 -m PEM ``` * NED -> HOST authentication. Used together with the existing user-name, user-password, port and protocol configuration items. ``` devices device dev-1 ned-settings cisco-apicdc ned-to-file-host-authentication-type devices device dev-1 ned-settings cisco-apicdc ned-to-file-host-private-key-path devices device dev-1 ned-settings cisco-apicdc ned-to-file-host-private-key-passphrase ``` * password - username/password auth; uses user-name and user-password. * shared-key - SSH pre-shared key; uses user-name, ned-to-file-host-private-key-path and ned-to-file-host-private-key-passphrase (passphrase optional). * APIC -> HOST authentication. Lets the APIC push hop use credentials/port/protocol that differ from the NED pull hop. ``` devices device dev-1 ned-settings cisco-apicdc apic-to-file-host-user-name devices device dev-1 ned-settings cisco-apicdc apic-to-file-host-authentication-type devices device dev-1 ned-settings cisco-apicdc apic-to-file-host-user-password devices device dev-1 ned-settings cisco-apicdc apic-to-file-host-private-key-path devices device dev-1 ned-settings cisco-apicdc apic-to-file-host-private-key-passphrase devices device dev-1 ned-settings cisco-apicdc apic-to-file-host-port devices device dev-1 ned-settings cisco-apicdc apic-to-file-host-protocol ``` * apic-to-file-host-user-name is the switch. Leave it empty to make the entire APIC hop inherit the NED-hop settings (user, password, port, protocol, auth-type, key path and passphrase) - the original single-credential behavior. Set it to use the independent apic-to-file-host-\* settings above. * password - uses apic-to-file-host-user-name and apic-to-file-host-user-password. * shared-key - uses apic-to-file-host-user-name, apic-to-file-host-private-key-path and apic-to-file-host-private-key-passphrase. The NED injects the key contents into the APIC export MO (authType="useSshKeyContents"). * Validation rules: * host and config-path are always required. * NED hop: user-name required. If shared-key, ned-to-file-host-private-key-path is required; otherwise user-password is required. port and protocol are required; protocol must be one of sftp/ftp/scp. ftp requires a password. scp requires local-host true. * APIC hop (enforced only when apic-to-file-host-user-name is set): if shared-key, apic-to-file-host-private-key-path is required; otherwise apic-to-file-host-user-password is required. apic-to-file-host-port and apic-to-file-host-protocol are required with the same protocol/scp/ftp rules. * Example: both hops via one shared SSH key (APIC hop inherits the NED hop). ``` devices device dev-1 ned-settings cisco-apicdc host 10.0.0.9 devices device dev-1 ned-settings cisco-apicdc config-path /uploads devices device dev-1 ned-settings cisco-apicdc user-name svc devices device dev-1 ned-settings cisco-apicdc ned-to-file-host-authentication-type shared-key devices device dev-1 ned-settings cisco-apicdc ned-to-file-host-private-key-path /var/opt/ncs/keys/apic_upload devices device dev-1 ned-settings cisco-apicdc ned-to-file-host-private-key-passphrase MyPass devices device dev-1 ned-settings cisco-apicdc protocol sftp ``` * Example: different credentials per hop (NED pulls with a key; APIC pushes with its own user/password over scp). ``` devices device dev-1 ned-settings cisco-apicdc host 10.0.0.9 devices device dev-1 ned-settings cisco-apicdc config-path /uploads devices device dev-1 ned-settings cisco-apicdc local-host true devices device dev-1 ned-settings cisco-apicdc user-name nedpuller devices device dev-1 ned-settings cisco-apicdc ned-to-file-host-authentication-type shared-key devices device dev-1 ned-settings cisco-apicdc ned-to-file-host-private-key-path /var/opt/ncs/keys/ned_key devices device dev-1 ned-settings cisco-apicdc apic-to-file-host-user-name apicpusher devices device dev-1 ned-settings cisco-apicdc apic-to-file-host-authentication-type password devices device dev-1 ned-settings cisco-apicdc apic-to-file-host-user-password ApicPush123 devices device dev-1 ned-settings cisco-apicdc apic-to-file-host-protocol scp devices device dev-1 ned-settings cisco-apicdc apic-to-file-host-port 22 ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://nso-docs.cisco.com/neds/cisco-provided-neds/cisco-apicdc/readme-ned-settings.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.