NSO Playground - System Install

Explore and experiment with the world of NSO on Cisco Code Exchange, where you can dive right in and try out examples in a user-friendly browser-based integrated development environment (IDE).

But wait, there's more! You can also contribute your examples and share them with everyone. The best part is your peers can play with your examples without installing anything.

If you are new to NSO, start with the NSO Learning Labs, where you can find step-by-step guides.

Variants

Two flavors of the NSO Playground are available. Choose the environment that suits you best:

• Local install. See the Local Install repository for more information.
• System install. Based on the official NSO container.
  • The environment associated with this repository.

See this guide to learn the difference between System and Local install.

The rest of this guide focuses on the System Install option.

Explore

Click here to start using Cisco Cloud IDE.

Or go to Cisco Code Exchange and start the environment. Click on the Run in Cloud IDE button on the right side of the Repo title.

Once you click the Run in Cloud IDE button, a Cloud IDE instance with the Github repository appears. You find your code under the ~/src directory.

NOTE: Click on the src directory to expand it and see the code of the repo cloned. Pay attention to the directory structure of the workspace.

How can I add my own example?

To create a new example, follow these steps.

NOTE: You must use your own repositories.

1. Develop your example locally on your computer.
   1. You can also develop an example on the Playground, but keep in mind the guidelines, especially the 2-hour container lifespan.
2. Push your example to the default branch of your GitHub repository.
3. In your README.md file, specify the NSO variant (System, Local install) you used for your example.
4. Submit your repository on https://developer.cisco.com/codeexchange/submit/
5. Once your submission is approved, your repository will be featured on the Cisco Cloud IDE.
6. Congratulations! You can now start exploring, playing, and sharing your awesome examples. Let your creativity flow!

Need help?

You can open an issue on the NSO Local install repository to ask for help, share feedback, or request new features.

Need an example?

You can try the following example to get familiar with the Cloud IDE Environment. Copy or type the next commands into the VS Code terminal.

The examples that you can find from the NSO example set $NCS_DIR/examples.ncs run with a local installation of NSO.

The following instructions show you how to run the example netsim-sshkey with an NSO system installation where NSO is already running.

For a detailed explanation see the getting started guide: Developing and Deploying a Nano Service and the README file in the $NCS_DIR/examples.ncs/development-guide/nano-services/netsim-sshkey/ directory.

In addition, a container-based variant of the example is available in the NSO-Developer repository.

1. Build the packages and copy them to the NSO run-time directory.

   EXAMPLE_DIR=${NCS_DIR}/examples.ncs/development-guide/nano-services/netsim-sshkey
   # Temporary fix pre-NSO 6.1.4
   sed -i.orig -e "s|user\[service.local_user\]|user\[service.remote_name\]|" $EXAMPLE_DIR/packages/distkey/python/distkey/distkey_app.py
   for f in $EXAMPLE_DIR/packages/*/src; do make -C $f all; done
   cp -r $EXAMPLE_DIR/packages/* $NCS_RUN_DIR/packages/

2. Reload the packages using the ncs_cmd tool through the NSO Management Agent API (MAAPI).

   ncs_cmd -dd -c 'maction "/packages/reload"'

3. Create, configure NSO, and start three simulated devices.

   ncs-netsim create-network $NCS_RUN_DIR/packages/ne 3 ex --dir ./netsim
   ncs-netsim ncs-xml-init > devices_init.xml
   ncs-netsim start

4. Configure a default authgroup for the developer user.

   echo "config; devices authgroups group default umap developer remote-name admin remote-password admin; commit" | ncs_cli -C -u developer -g ncsadmin

5. Load the XML configuration files for device and service notification config using the ncs_load tool through NSO MAAPI.

   ncs_load -dd -m -l devices_init.xml
   ncs_load -dd -m -l $EXAMPLE_DIR/service_notif_init.xml

6. Generate keys, distribute the public key, and configure NSO for public key authentication with the three network elements.

   ncs_cli -n -u developer -g ncsadmin -C << EOF
   devices sync-from
   config
   pubkey-dist key-auth ex0 developer remote-name admin authgroup-name default passphrase "GThunberg18!"
   top pubkey-dist key-auth ex1 developer remote-name admin authgroup-name default passphrase "GThunberg18!"
   top pubkey-dist key-auth ex2 developer remote-name admin authgroup-name default passphrase "GThunberg18!"
   commit dry-run
   commit
   EOF

7. Show the nano service plan status.

   echo "show pubkey-dist key-auth plan component | tab | nomore" | ncs_cli -C -u developer -g ncsadmin

8. Show the configuration added to NSO and network elements.

   ncs_cli -n -u developer -g ncsadmin -C << EOF
   show running-config devices authgroups group umap developer
   show running-config devices device authgroup
   show running-config devices device config aaa authentication users user admin authkey | nomore
   EOF

9. Show the generated private and public keys.

   cat $NCS_RUN_DIR/*ed25519*

10. Delete the nano service to revert to password-based network element authentication.

ncs_cli -n -u developer -g ncsadmin -C << EOF
config
no pubkey-dist
commit dry-run
commit
EOF

11. Show the restored configuration for password authentication.

ncs_cli -n -u developer -g ncsadmin -C << EOF
show running-config devices authgroups group umap developer
show running-config devices device authgroup
show running-config devices device config aaa authentication users user admin authkey
EOF

Explore and play with the NSO Example Collection

Go to $NCS_DIR > examples.ncs in the VS Code workspace or use the terminal.

cd $NCS_DIR/examples.ncs/
developer:examples.ncs > ll
total 28
drwxr-xr-x 1 developer ncsadmin   267 Jun 28 11:38 .
drwx------ 1 developer ncsadmin   294 Jul 18 13:33 ..
-rw-r--r-- 1 developer ncsadmin 27052 Jun 28 11:38 README
drwxr-xr-x 1 developer ncsadmin    27 Jun 28 11:05 crypto
drwxr-xr-x 1 developer ncsadmin    36 Jun 28 11:05 datacenter
drwxr-xr-x 1 developer ncsadmin   261 Jun 28 11:38 development-guide
drwxr-xr-x 1 developer ncsadmin    27 Jun 28 11:05 generic-ned
drwxr-xr-x 1 developer ncsadmin    50 Jun 28 11:05 getting-started
drwxr-xr-x 1 developer ncsadmin    26 Jun 28 11:05 high-availability
drwxr-xr-x 1 developer ncsadmin    69 Jun 28 11:05 misc
drwxr-xr-x 1 developer ncsadmin   143 Jun 28 11:05 service-provider
drwxr-xr-x 1 developer ncsadmin    19 Jun 28 11:05 snmp-ned
drwxr-xr-x 1 developer ncsadmin   155 Jun 28 11:38 snmp-notification-receiver
drwxr-xr-x 1 developer ncsadmin    53 Jun 28 11:05 web-server-farm
drwxr-xr-x 1 developer ncsadmin    31 Jun 28 11:05 web-ui

NOTE: The NSO examples target Local Install and must be modified to run on a System Install. See the NSO Getting Started Guide for more details.

More Playground examples?

Go to Cisco Code Exchange to find more examples created by the community.

Guidelines

• Avoid any confidential information. When you share code, it becomes public.
• NSO Playground is designed for short "How-to" examples. Consider the following points when you create instructions:
  • The NSO Playground container is ephemeral. Save your work in your remote GitHub repository if you want to keep it.
    • To save your work permanently, remember to merge your changes in your remote GitHub repository.
  • The container in the NSO Playground has a lifespan of 2 hours. After 2 hours, the system automatically destroys the container.
    • The system prompts you to start a new session to continue working.
    • Time starts the moment that you access the URL of the NSO Playground environment.
  • If you must work on NSO for a longer time, consider using a free NSO evaluation copy or reserve a free DevNet Sandbox.
• You can use only one environment at a time in Code Exchange.
  • If you open multiple environments for the same user, Code Exchange closes the oldest environment.

Recommendations

• Create examples with an "Infrastructure as a Code" mindset. This means everything needed to create your examples is in your GitHub repository.

• Avoid specifying NSO versions in the code, we update the playground continuously.

• As seen in the examples, use environment variables when developing.

  • $NCS_DIR Is a handy environment variable.
  • env | grep -i ncs Shows other environment variables available by ncs.

• The directory structure of the workspace matters. Consider it when creating an example.

• Always add a README.md file to the root directory of your repository with instructions on how to set up or run your example.

• Use the preview feature (right click) in VS Code to see the markdown files formatted.

  

FAQ

• Where is the NSO webUI?

  • Follow the steps that described on Enable the NSO webUI

• Can I reset the environment?

  • Yes, click on the reset button at the bottom-right corner. This action fully resets the container.

    

  • If you want to keep some work, make sure you save it on your remote GitHub repository first.

• How to enable the VS Code NSO Developer Studio - Explorer?

  • This extension is already present on the playground.
  • To use the extension, follow next the steps:
    • Enable the NSO webUI and authentication. See enable the NSO webUI
    • Refresh the explorer extension (load icon inside the extension).

• Which NEDs come with the container?

  • Example NEDs, which must be considered as examples. NEDs in the container are only used to run the simulated networks. Do not use these example NEDs with real devices.

    developer:~ > ls -1 $NCS_DIR/packages/neds/
    a10-acos-cli-3.0
    alu-sr-cli-3.4
    cisco-asa-cli-6.6
    cisco-ios-cli-3.0
    cisco-ios-cli-3.8
    cisco-iosxr-cli-3.0
    cisco-iosxr-cli-3.5
    cisco-nx-cli-3.0
    dell-ftos-cli-3.0
    juniper-junos-nc-3.0
    developer:~ > ls -1 $NCS_DIR/packages/neds/ | wc -l
    10
    developer:~ >

• My code is approved and is already published on Cisco Code Exchange, why isn't it visible on the playground?

  • Expand the /home/developer/src in the workspace.
  • Or do: ls -l /home/developer/src