search

CiscoDevNet / yang-explorer

An open-source Yang Browser and RPC Builder Application
Apache License 2.0
437 stars 177 forks source link

readme

Copyright 2015, Cisco Systems, Inc

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

END OF SUPPORT

As of 18th August 2020 this application is no longer maintained. Developers are free to use the code as-is, including forking, but no more updates will be forthcoming from the project maintainers and any new or outstanding issues will neither be tracked nor responded to.

For a potential alternative, see YANG Suite.

1. Description

An open-source Yang Browser and RPC Builder Application to experiment with Yang Data Models

Features

Screenshots:

alt tag alt tag alt tag alt tag

2. Installation

2.1 First time installation

Prerequisite:

Download and install:

   git clone https://github.com/CiscoDevNet/yang-explorer.git
   cd yang-explorer
   bash setup.sh

   Note: sudo may be required if you do not use virtualenv.

See section 7 Troubleshooting for more:

   If you get installation error for missing python.h or xmlversion.h try installing
   dependency packages:

   Ubuntu: sudo apt-get install libxml2-dev libxslt1-dev python-dev zlib1g-dev
   Fedora: sudo dnf install libxml2-devel libxslt-devel python-devel zlib-devel

2.2 Update exising installation

  cd <install-root>/yang-explorer
  git stash (if you have local changes)
  git pull origin
  git stash apply (if you have local changes)
  bash setup.sh

2.3 Backing up data

YangExplorer data can be backed up from data directory and it is portable to new servers -

   cp -r <install-root>/yang-explorer/server/data <backup-location>/data

Restore from backup location -

   cd <install-root>/yang-explorer/server

   # move current data to tmp location
   mv data data_old

   # replace data from backup location
   cp -r <backup-location>/data data

3. Running YangExplorer

3.1 Running with localhost

Start Server:

   cd <install-root>/yang-explorer
   [sudo] ./start.sh &

   Note: sudo may be required if you did not use virtualenv during installation.

Start Explorer:

   http://localhost:8088/static/YangExplorer.html

3.2 Running with ip-address (Shared server)

Start Server:

   # Determine <ip-address> using if-config

   # Add ip-address/port in YangExplorer.html after following line:
   cd <install-root>/yang-explorer/server/static
      vi YangExplorer.html
      var flashvars = {}; 
+     flashvars.host = '<ip-address>';
+     flashvars.port = '8088';

   # save & quit

   # Update ip-address in startup script
      cd <install-root>/yang-explorer
      vi start.sh
      (update HOST variable with <ip-address>)
   # save & quit

   ./start.sh

   Note: sudo may be required if you did not use virtualenv during installation.

Start Explorer:

   http://<ip-address>:8088/static/YangExplorer.html

4. Caveats

5. User Guide (TBD)

5.1 Work Flow

5.2.1 Login:

YangExplorer uses user accounts to manage workspaces. You can create a user account using admin page (See 5.3.1 Creating User Account) or use the predefined login (guest/guest). You must login (click on the Login button on top right corner)

You can use guest login (guest/guest) or newly created account. alt tag

5.2.2 Adding/Deleing Yang Models:

Upload using yang-explorer user interface (TBD: screen shot is out-of-date)

alt tag

Sync from Device

Upload models using server console

   cd <install-root>/yang-explorer
   source v/bin/activate
   cd server
   python manage.py --user <username> --git <git-url> --dir <path/to/yang/models>

   example: local upload (assumes models are already available at dir path)
   python manage.py bulkupload --user guest --dir /users/prgohite/git/yang/vendor/cisco/xr/531

   example: git upload
   python manage.py bulkupload --user guest --git https://github.com/YangModels/yang.git --dir vendor/cisco/xr/531

All models must be compiled successfully, in case of any error none of the models will be uploaded to yang-explorer.

5.2.3 Generating the model dependency graph:

5.2.4 Creating RPCs:

You can explore yang models in explorer area (left pane) using tree navigation: alt tag

5.2.5 Executing RPCs:

5.2.6 Generating Python example:

5.2.7 Saving RPCs to Collection:

5.2.8 Loading saved RPC:

5.3 Admin Tasks

5.3.1 Creating User Account (optional):

Creating user account is optional as you can use default guest/guest login, however creating user account can be userful if you have a shared yang-explorer installation.

5.3.2 Creating Device Profiles:

Device profiles can be created to quickly populate device info from drop-down list in yang-explorer.

Note: You can use default user login (guest/guest)

5.3.3 Creating Collection:

Collections can be used to save user generated RPCs on the server so that saved RPCs can be re-used.

Note: You can use default user login (guest/guest)

6 Misc Features

6.1 UI Model Tree annotations

Targeted content in YangExplorer UI tree can be annotated in different color, usually to represent additional information about of the Yang model node.

Installation:

  cd <install-root>/yang-explorer
  bash setup.sh -a <path to annotation json file>

Please refresh browser to reflect changes. You should see UI model tree node name in different color as per annotation file.

Uninstall:

  cd <install-root>/yang-explorer
  bash setup.sh -r

7 Troubleshooting

7.1 Installation

7.1.1 error for missing python.h or xmlversion.h

7.1.2 django.db.utils.OperationalError: near "񐁂򐁇N": syntax error

7.1.3 After install if you are not able to login using guest/guest try one of the following

7.1.4 Installation failed due to python 3 not supported

Python 3 is not supported by ncclient. Please install python 2.7 before proceeding futher. If python 2.7 is already installed on your system along with python 3, virtualenv may try to create python 3 environment. You can do following -

   cd YangExplorer
   rm -rf v

   # find path to python 2.7 on your system
   ➜  ~  which python2.7   
   /usr/bin/python2.7

   # create a virtualenv with python 2.7, path may differ based on your installation
   virtualenv -p /usr/bin/python2.7 v

   # rerun setup
   setup.sh

7.2 Yang Model Upload

7.2.1 Failure during upload of yang model