{"id":21636099,"url":"https://github.com/ttafsir/evengsdk","last_synced_at":"2025-04-05T06:10:20.808Z","repository":{"id":38638497,"uuid":"232674603","full_name":"ttafsir/evengsdk","owner":"ttafsir","description":"Open source Python library and command line utilities for EVE-NG API","archived":false,"fork":false,"pushed_at":"2025-03-13T07:30:10.000Z","size":1906,"stargazers_count":69,"open_issues_count":62,"forks_count":15,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-04T17:55:19.815Z","etag":null,"topics":["api","eve-ng","eve-ng-api","eve-ng-cli","labs","netdevops","network-automation","network-programming","networking","networking-labs"],"latest_commit_sha":null,"homepage":"https://ttafsir.github.io/evengsdk/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ttafsir.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-08T22:42:20.000Z","updated_at":"2025-03-07T07:41:33.000Z","dependencies_parsed_at":"2023-01-30T20:16:08.706Z","dependency_job_id":"5880987f-62d5-445a-9592-bd65ca0e3dfa","html_url":"https://github.com/ttafsir/evengsdk","commit_stats":{"total_commits":131,"total_committers":4,"mean_commits":32.75,"dds":0.4122137404580153,"last_synced_commit":"ebbd28fce594912fb9a6d3a0e2ef5ae0f2a91604"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ttafsir%2Fevengsdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ttafsir%2Fevengsdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ttafsir%2Fevengsdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ttafsir%2Fevengsdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ttafsir","download_url":"https://codeload.github.com/ttafsir/evengsdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247294541,"owners_count":20915340,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","eve-ng","eve-ng-api","eve-ng-cli","labs","netdevops","network-automation","network-programming","networking","networking-labs"],"created_at":"2024-11-25T03:29:49.986Z","updated_at":"2025-04-05T06:10:20.775Z","avatar_url":"https://github.com/ttafsir.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# evengsdk\n\n![license](https://img.shields.io/github/license/ttafsir/evengsdk)\n[![Downloads](https://pepy.tech/badge/eve-ng)](https://pepy.tech/project/eve-ng)\n[![PyPI version](https://badge.fury.io/py/eve-ng.svg)](https://badge.fury.io/py/eve-ng)\n\nDocumentation: https://ttafsir.github.io/evengsdk\n\nOpen source library and command line utilities to work with the [EVE-NG](https://www.eve-ng.net/)  [REST API](https://www.eve-ng.net/index.php/documentation/howtos/how-to-eve-ng-api/) .\n\nEvegnsdk allows you to quickly build network topologies in EVE-NG for testing and development. The CLI tool also enables you quickly integrate EVE-NG into your CI/CD toolset for automated testing and validation.\n\n## Requirements\n\n* Python 3.8+\n* An EVE-NG instance\n\n## :rocket:Installation\n\nYou can install `evengsdk` using pip\n\n```sh\npip install eve-ng\n```\n\n## Basic Usage\n\nYou can interact with the EVE-NG API through the `client.api` interface\n\n```python\n\u003e\u003e\u003e from evengsdk.client import EvengClient\n\u003e\u003e\u003e from pprint import pprint\n\u003e\u003e\u003e\n\u003e\u003e\u003e client = EvengClient(\"10.246.32.254\", log_file=\"test.log\")\n\u003e\u003e\u003e client.login(username=\"admin\", password=\"eve\")\n\u003e\u003e\u003e\n\u003e\u003e\u003e resp = client.api.list_node_templates()\n\u003e\u003e\u003e pprint(resp.get(\"data\"))\n{'a10': 'A10 vThunder.missing',\n 'acs': 'Cisco ACS.missing',\n 'aruba': 'Aruba WiFi Controller.missing',\n 'arubacx': 'Aruba OS-CX Virtual Switch.missing',\n 'asa': 'Cisco ASA.missing',\n 'asav': 'Cisco ASAv',\n 'bigip': 'F5 BIG-IP LTM VE',\n 'cumulus': 'Cumulus VX',\n\n \u003cOUTPUT OMMITTED FOR BREVITY\u003e\n\n 'linux': 'Linux',\n 'mikrotik': 'MikroTik RouterOS.missing',\n 'nsx': 'VMWare NSX.missing',\n 'nxosv9k': 'Cisco NX-OSv 9K',\n 'paloalto': 'Palo Alto.missing',\n 'pfsense': 'pfSense Firewall.missing',\n 'vcenter': 'VMWare vCenter.missing',\n 'vios': 'Cisco vIOS Router',\n 'viosl2': 'Cisco vIOS Switch',\n 'vmx': 'Juniper vMX.missing',\n 'vwlc': 'Cisco vWLC.missing',\n 'vyos': 'VyOS',\n 'xrv9k': 'Cisco XRv 9000.missing'}\n\u003e\u003e\u003e\n```\n#### Example: Build a Lab\n\n```python\nfrom evengsdk.client import EvengClient\n\n\nclient = EvengClient(\"10.246.32.254\", log_file=\"test.log\", ssl_verify=False, protocol=\"https\")\nclient.disable_insecure_warnings()  # disable warnings for self-signed certificates\nclient.login(username=\"admin\", password=\"eve\")\nclient.set_log_level(\"DEBUG\")\n\n# create a lab\nlab = {\"name\": \"test_lab\", \"description\": \"Test Lab\", \"path\": \"/\"}\nresp = client.api.create_lab(**lab)\nif resp['status'] == \"success\":\n  print(\"lab created successfully.\")\n\n# we need the lab path to create objects in the lab\nlab_path = f\"{lab['path']}{lab['name']}.unl\"\n\n# create management network\nmgmt_cloud = {\"name\": \"eve-mgmt\", \"network_type\": \"pnet1\"}\nclient.api.add_lab_network(lab_path, **mgmt_cloud)\n\n# create Nodes\nnodes = [\n    {\"name\": \"leaf01\", \"template\": \"veos\", \"image\": \"veos-4.22.0F\", \"left\": 50},\n    {\"name\": \"leaf02\", \"template\": \"veos\", \"image\": \"veos-4.22.0F\", \"left\": 200},\n]\nfor node in nodes:\n    client.api.add_node(lab_path, **node)\n\n# connect nodes to management network\nmgmt_connections = [\n    {\"src\": \"leaf01\", \"src_label\": \"Mgmt1\", \"dst\": \"eve-mgmt\"},\n    {\"src\": \"leaf02\", \"src_label\": \"Mgmt1\", \"dst\": \"eve-mgmt\"}\n]\nfor link in mgmt_connections:\n    client.api.connect_node_to_cloud(lab_path, **link)\n\n# create p2p links\np2p_links = [\n    {\"src\": \"leaf01\", \"src_label\": \"Eth1\", \"dst\": \"leaf02\", \"dst_label\": \"Eth1\"},\n    {\"src\": \"leaf01\", \"src_label\": \"Eth1\", \"dst\": \"leaf02\", \"dst_label\": \"Eth2\"},\n]\nfor link in p2p_links:\n    client.api.connect_node_to_node(lab_path, **link)\n\nclient.logout()\n```\n\n## :tv: The `eve-ng` CLI Application\n\nThe CLI application makes it very simple to quick work with EVE-NG, especially in situation where you would like to automate lab builds and testing using CI/CD.\n\nThe CLI application provides an interface to manage EVE-NG objects including:\n\n* `Folders` - manage the directory-like structures that contains labs\n* `Labs` - manage labs and objects inside labs (nodes, networks, links, etc)\n  * nodes\n  * networks\n* `Users` - manage system users\n* `System` - View system status and resources (node templates, network types, user roles, etc..)\n\n```zsh\n➜ eveng --help\nUsage: eveng [OPTIONS] COMMAND [ARGS]...\n\n  CLI application to manage EVE-NG objects\n\nOptions:\n  --host TEXT           [required]\n  --username TEXT       [default: (current user); required]\n  --password TEXT       [required]\n  --port INTEGER        HTTP port to connect to. Default is 80\n  --debug / --no-debug  Enables or disables debug mode.\n  -v, --verbose         Enables verbosity.\n  --help                Show this message and exit.\n\nCommands:\n  folder               folder sub commands\n  lab                  lab sub commands\n  list-network-types   list EVE-NG network types\n  list-node-templates  list EVE-NG node templates\n  list-user-roles      list EVE-NG user roles\n  node                 node sub commands\n  show-status          View EVE-NG server status\n  show-template        get EVE-NG node template details\n  user                 user sub commands\n  version              display library version\n```\n\n### CLI sample output\n\n![image-20220114112752004](./cli-output.png)\n\n## :gear: Configuration\n\nIt is simple enough to pass the proper flags to `eve-ng` specify details for your EVE-NG host. However, you may also pass the connection details as environment variables. You can set the following `evengsdk` environment variables:\n\n* `EVE_NG_HOST ` - EVE-NG host name or IP address\n* `EVE_NG_USERNAME` - EVE-NG username\n* `EVE_NG_PASSWORD ` EVE-NG API/GUI password\n* `EVE_NG_LAB_PATH` - EVE-NG default lab path. Ex. `/myLab.unl`\n\nYou may set the variables and export them to your shell environment. You can also define your environment variables in a `.env` folder that will automatically be sourced. The example. below shows the contents of a `.env`  file that will permit you to both source the file and automatically load the variables as needed.\n\n```txt\nexport EVE_NG_HOST=192.168.2.100\nexport EVE_NG_USERNAME=admin\nexport EVE_NG_PASSWORD=eve\nexport EVE_NG_PORT=80\nexport EVE_NG_PROTOCOL=http\nexport EVE_NG_SSL_VERIFY=False\nexport EVE_NG_INSECURE=True\nexport EVE_NG_LAB_PATH='/mylab.unl'\n```\n\n## 🏗️ Topology Builder\n\nThe CLI application allows you to build lab topologies using a declarative model in order to quickly spin a lab and configure nodes using configuration files or jinja templates. Below is a sample topology that is the `examples` directory of this project.\n\n```yaml\n---\n  name: test\n  description: Arista VEOS leaf-spine lab\n  path: \"/\"\n  nodes:\n    - name: leaf01\n      template: veos\n      image: veos-4.22.0F\n      node_type: qemu\n      left: 50\n      top: 135\n      configuration:\n        file: examples/configs/test_leaf01.cfg\n    - name: leaf02\n      template: veos\n      image: veos-4.22.0F\n      node_type: qemu\n      left: 200\n      top: 135\n      configuration:\n        template: base.j2\n        vars:\n          hostname: leaf02\n          management_address: 10.10.10.1\n    - name: leaf03\n      template: veos\n      image: veos-4.22.0F\n      node_type: qemu\n      left: 350\n      top: 135\n      configuration:\n        template: base.j2\n        vars: examples/data/leaf03.yml\n    - name: leaf04\n      template: veos\n      image: veos-4.22.0F\n      node_type: qemu\n      left: 500\n      top: 135\n    - name: spine01\n      template: veos\n      image: veos-4.22.0F\n      node_type: qemu\n      left: 150\n      top: 474\n    - name: spine02\n      template: veos\n      image: veos-4.22.0F\n      node_type: qemu\n      left: 350\n      top: 474\n  networks:\n    - name: vCloud\n      network_type: pnet1\n      visibility: 1\n      top: 300\n      left: 475\n  links:\n    network:\n      - {\"src\": \"leaf01\", \"src_label\": \"Mgmt1\", \"dst\": \"vCloud\"}\n      - {\"src\": \"leaf02\", \"src_label\": \"Mgmt1\", \"dst\": \"vCloud\"}\n      - {\"src\": \"leaf03\", \"src_label\": \"Mgmt1\", \"dst\": \"vCloud\"}\n      - {\"src\": \"leaf04\", \"src_label\": \"Mgmt1\", \"dst\": \"vCloud\"}\n      - {\"src\": \"spine01\", \"src_label\": \"Mgmt1\", \"dst\": \"vCloud\"}\n      - {\"src\": \"spine02\", \"src_label\": \"Mgmt1\", \"dst\": \"vCloud\"}\n    node:\n      - {\"src\": \"leaf01\", \"src_label\": \"Eth3\", \"dst\": \"spine01\", \"dst_label\": \"Eth1\"}\n      - {\"src\": \"leaf02\", \"src_label\": \"Eth3\", \"dst\": \"spine01\", \"dst_label\": \"Eth2\"}\n      - {\"src\": \"leaf03\", \"src_label\": \"Eth3\", \"dst\": \"spine01\", \"dst_label\": \"Eth3\"}\n      - {\"src\": \"leaf04\", \"src_label\": \"Eth3\", \"dst\": \"spine01\", \"dst_label\": \"Eth4\"}\n      - {\"src\": \"leaf01\", \"src_label\": \"Eth2\", \"dst\": \"spine02\", \"dst_label\": \"Eth1\"}\n      - {\"src\": \"leaf02\", \"src_label\": \"Eth2\", \"dst\": \"spine02\", \"dst_label\": \"Eth2\"}\n      - {\"src\": \"leaf03\", \"src_label\": \"Eth2\", \"dst\": \"spine02\", \"dst_label\": \"Eth3\"}\n      - {\"src\": \"leaf04\", \"src_label\": \"Eth2\", \"dst\": \"spine02\", \"dst_label\": \"Eth4\"}\n\n```\n\nTo create a topology from the example above simply run the following command\n\n```sh\neve-ng lab create-from-topology -t examples/test_topology.yml --template-dir examples/templates\n```\n\nBy default, the configuration tool searches for templates in `templates` directory, but you can use `--template-dir` as shown above to specify another location.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fttafsir%2Fevengsdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fttafsir%2Fevengsdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fttafsir%2Fevengsdk/lists"}