# eve2cml
[](https://pypi.org/project/eve2cml/) [](https://coveralls.io/github/CiscoDevNet/eve2cml?branch=main) [](https://github.com/CiscoDevNet/eve2cml/actions/workflows/python-package.yml)
Convert EVE-NG topology files either in ZIP format or in plain-text XML (.unl) to CML2 YAML format.
> [!CAUTION]
>
> This is considered "beta" as in "it works for me but might have bugs or things don't work as you expect them to work." So, use with care and at your own risk.
## Online conversion
The easiest way to convert files into CML format is to use the online converter provided [here](https://www.marcuscom.com/eve2cml/). Simply upload your UNL or ZIP files and the tool will convert them for you, using the eve2cml package in the background.
## Installation
eve2cml requires Python 3, it has been tested with 3.9, 3.10, 3.11 and 3.12. You can either
- use [pipx](https://github.com/pypa/pipx) to install it in an isolated environment:
```plain
$ pipx install eve2cml
installed package eve2cml 0.1.0b4, installed using Python 3.10.12
These apps are now globally available
- eve2cml
done! ✨ 🌟 ✨
$ eve2cml --version
eve2cml 0.1.0b4
$
```
- pip-install it from PyPI by running `pip install eve2cml`. This will install the package into your current Python environment. It is suggested to use a virtual or local environment instead of the system / global environment.
## Development
eve2cml uses [UV](https://docs.astral.sh/uv/) to manage Python related things like dependencies, virtual environments and Python installations. At a minimum, Git and UV must be installed as prerequisites. After UV is installed, it can install Python for you (`uv python install...` and you can run `make sync` and a virtual environment will be created, all dependencies will be installed and a dev-version of eve2cml will be available. Changes should be pushed into a new branch to a forked copy of the repository and result, eventually, in a pull request.
There's a couple of make targets available which help with developing eve2cml:
- `make covo`, shows code coverage, opens in a browser window
- `make test`, runs all available tests
- `make format`, formats the code with ruff
- `make build`, builds distribution packages in `dist`
- `make clean`, cleans up created files (also `mrproper`, which deletes the .venv)
## Mapping node types
There's some default node type mappings which can be dumped into a file using the `--dump` flag.
The mapper defines three elements:
- `interface_lists`: A map with a list of interface names for each mapped CML node definitions. The key is the CML node definition ID
- `unknown_type`: Which node definition ID should be inserted into the topology if the EVE node type is not defined in the mapper (a string like "desktop")
- `map`: Maps EVE node types into CML node and image definitions. The map key is an EVE node type where the format is "eve-node-type:eve-node-template:eve-node-image" (separated by colons). An example is `qemu:linux`. When the image part is missing then the CML default image for the mapped node type is used. The value for each key is of the form:
- `image_def`: the CML image definition ID for this node definition ID (can safely be null/undefined)
- `node_def`: the mapped CML node definition ID
- `override`: a boolean. It determines whether values like CPU or memory should be taken from the EVE definition. If `true` then the EVE values will not be used, the default values from CML for this particular node type will then be used instead
There's a specific "corner case" where the type is identical to the template (e.g. "iol:iol" or "docker:docker"). In this particular case, mapper keys are searched for partial matches where the map key matches the beginning of the provided EVE image. For example, "iol:iol:i86bi_linux_l2:" matches all IOL images that start with `i86bi_linux_l2` and maps them (by default) into `ioll2-xe`.
After modification / adding more or different node type mappings to the exported map YAML, use the file via the `--mapper modified_map.yaml` flag.
Disclaimer: There's certainly things out there which do not properly translate. If you encounter anything then raise an issue in the issue tracker and I'll look into it.
> [!NOTE]
> It is possible to change node types when importing. For example, you might want to change IOSv-L2 instances to IOLL2-XE instances by providing a custom import map. However, this does **NOT** change the device configuration of the imported nodes. So, if the configuration uses `GigabitEthernet0/4` in the original IOSv-L2 configuration then it is your responsibility to change this to `Ethernet1/0` for the configuration of the imported IOLL2-XE device. This can be easily done via a sed script or using a text editor and global search and replace. But this might be more involved depending on the original/target device type. See the [Change configurations](#change-configurations) section below for an example.
## Usage
```plain
$ eve2cml -h
usage: eve2cml [-h] [-V] [--level {debug,info,warning,error,critical}] [--stdout] [--nocolor] [--dump] [--mapper MAPPER] [-t] [--all] file_or_zip [file_or_zip ...]
Convert UNL/XML topologies to CML2 topologies
positional arguments:
file_or_zip Path to either a UNL or ZIP with UNL file
optional arguments:
-h, --help show this help message and exit
-V, --version show program's version number and exit
--level {debug,info,warning,error,critical}
specify the log level, default is warning
--stdout do not store in files, print to stdout
--nocolor no color log output
--dump Dump the mapper as YAML
--mapper MAPPER custom mapper YAML file
-t, --text text output
--all print all objects in text mode
Example: eve2cml exportedlabs.zip
$
```
## Change configurations
With a custom mapper file, node types can be modified while importing. For example, adding map entries like the following
```yaml
qemu:vios:
image_def: null
node_def: iol-xe
override: false
qemu:viosl2:
image_def: null
node_def: ioll2-xe
override: false
```
to the mapper will change all IOSv instances to IOL-XE instances and all IOSv-L2 instances to IOLL2-XE instances. However, the day zero configuration files of those nodes will not be modified to match the now different interface names. In this particular case, where most of the configuration between IOSv and IOL-XE is identical *except for the interface names*, a simple sed script can do the trick. Here's how this can be done:
1. create a sed script file with this content, filename `ios2iol-config`:
```plain
s#GigabitEthernet0/0#Ethernet0/0#
s#GigabitEthernet0/1#Ethernet0/1#
s#GigabitEthernet0/2#Ethernet0/2#
s#GigabitEthernet0/3#Ethernet0/3#
s#GigabitEthernet0/4#Ethernet1/0#
s#GigabitEthernet0/5#Ethernet1/1#
s#GigabitEthernet0/6#Ethernet1/2#
s#GigabitEthernet0/7#Ethernet1/3#
s#GigabitEthernet0/8#Ethernet2/0#
s#GigabitEthernet0/9#Ethernet2/1#
s#GigabitEthernet0/10#Ethernet2/2#
s#GigabitEthernet0/11#Ethernet2/3#
s#GigabitEthernet0/12#Ethernet3/0#
s#GigabitEthernet0/13#Ethernet3/1#
s#GigabitEthernet0/14#Ethernet3/2#
s#GigabitEthernet0/15#Ethernet3/3#
```
2. dump the default / built-in mapper into a file (`--dump` option)
3. modify the mapper to include the changes outlined above
4. convert the topology with the modified map file (`--mapper` option)
5. run `sed -f ios2iol-config lab.yaml >lab_with_configs_changed.yaml`
This will change all occurrences within the CML lab file from IOSv notation to IOL notation.
## Contributing
If you have a more complete map file with additional or more specific node type mappings or if you have improved the code, fixed a bug or a typo or added a new feature then I more than welcome you to raise a pull request!
## Issues
If you encounter any issues with the converter then please open a issue in the [GitHub issue tracker](https://github.com/CiscoDevNet/eve2cml/issues).
### IOL interfaces
There's a known issue with the maximum number of interfaces defined in the shipping node definitions for IOL and IOL-L2. As for the released version of CML 2.7.0, the maximum number of interfaces is 16. If you have topologies which use more interfaces (`Ethernet4/0` and up) then you need to add the additional interfaces to the node definition in CML (Tools -> Node and image definitions -> IOL / IOL-L2). In the interface section, add the required interfaces and name them properly. Don't forget to click "Update" at the bottom when done.
This is fixed in the 2.7.1 release, once available.
The converter has now 32 interfaces defined in the mapper (`Ethernet0/0` to `Ethernet7/3`).
### Known issues
There's a few things which are known to cause issues. Some of them might be addressable by code changes in the converter and/or changes on the CML side of things. And some might just not be possible at all.
- Text objects in EVE can have a background color. The converter adds additional rectangles behind the text object in CML. It "guesses" the size of these rectangles. Those guesses are inaccurate.
- Font (names) might not translate well. I think there's a general issue with serif vs. sans-serif mapping.
- Images (PNGs) as part of a topology are ignored as there's no representation for them in CML.
- More complex text boxes in EVE do not translate well into the more simple text annotation of CML. For color, size and font name, the first occurrence is used for the entire text object. Things like bullet lists etc. are completely ignored.
- EVE multi-point networks are represented by unmanaged switches in CML. They have max 32 ports. That might not be enough.
- Workbooks ("tasks") are not stored anywhere. Unclear at the moment, if and how to handle them.
Also check the [TODO](/TODO.md) file for additional things that will likely be added in subsequent releases.
Raw data
{
"_id": null,
"home_page": null,
"name": "eve2cml",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "automation, network-programming, simulation, tools, virtualization",
"author": null,
"author_email": "Ralph Schmieder <rschmied@cisco.com>",
"download_url": "https://files.pythonhosted.org/packages/b2/b3/bfc2e709414dd0c3da85e1686d9fb0299237aea3d5eb4da67340870205a1/eve2cml-0.1.2.tar.gz",
"platform": null,
"description": "# eve2cml\n\n[](https://pypi.org/project/eve2cml/) [](https://coveralls.io/github/CiscoDevNet/eve2cml?branch=main) [](https://github.com/CiscoDevNet/eve2cml/actions/workflows/python-package.yml)\n\n\n\nConvert EVE-NG topology files either in ZIP format or in plain-text XML (.unl) to CML2 YAML format.\n\n> [!CAUTION]\n>\n> This is considered \"beta\" as in \"it works for me but might have bugs or things don't work as you expect them to work.\" So, use with care and at your own risk.\n\n## Online conversion\n\nThe easiest way to convert files into CML format is to use the online converter provided [here](https://www.marcuscom.com/eve2cml/). Simply upload your UNL or ZIP files and the tool will convert them for you, using the eve2cml package in the background.\n\n## Installation\n\neve2cml requires Python 3, it has been tested with 3.9, 3.10, 3.11 and 3.12. You can either\n\n- use [pipx](https://github.com/pypa/pipx) to install it in an isolated environment:\n\n ```plain\n $ pipx install eve2cml\n installed package eve2cml 0.1.0b4, installed using Python 3.10.12\n These apps are now globally available\n - eve2cml\n done! \u2728 \ud83c\udf1f \u2728\n\n $ eve2cml --version\n eve2cml 0.1.0b4\n\n $\n ```\n\n- pip-install it from PyPI by running `pip install eve2cml`. This will install the package into your current Python environment. It is suggested to use a virtual or local environment instead of the system / global environment.\n\n## Development\n\neve2cml uses [UV](https://docs.astral.sh/uv/) to manage Python related things like dependencies, virtual environments and Python installations. At a minimum, Git and UV must be installed as prerequisites. After UV is installed, it can install Python for you (`uv python install...` and you can run `make sync` and a virtual environment will be created, all dependencies will be installed and a dev-version of eve2cml will be available. Changes should be pushed into a new branch to a forked copy of the repository and result, eventually, in a pull request.\n\nThere's a couple of make targets available which help with developing eve2cml:\n\n- `make covo`, shows code coverage, opens in a browser window\n- `make test`, runs all available tests\n- `make format`, formats the code with ruff\n- `make build`, builds distribution packages in `dist`\n- `make clean`, cleans up created files (also `mrproper`, which deletes the .venv)\n\n## Mapping node types\n\nThere's some default node type mappings which can be dumped into a file using the `--dump` flag.\n\nThe mapper defines three elements:\n\n- `interface_lists`: A map with a list of interface names for each mapped CML node definitions. The key is the CML node definition ID\n\n- `unknown_type`: Which node definition ID should be inserted into the topology if the EVE node type is not defined in the mapper (a string like \"desktop\")\n\n- `map`: Maps EVE node types into CML node and image definitions. The map key is an EVE node type where the format is \"eve-node-type:eve-node-template:eve-node-image\" (separated by colons). An example is `qemu:linux`. When the image part is missing then the CML default image for the mapped node type is used. The value for each key is of the form:\n\n - `image_def`: the CML image definition ID for this node definition ID (can safely be null/undefined)\n - `node_def`: the mapped CML node definition ID\n - `override`: a boolean. It determines whether values like CPU or memory should be taken from the EVE definition. If `true` then the EVE values will not be used, the default values from CML for this particular node type will then be used instead\n\n There's a specific \"corner case\" where the type is identical to the template (e.g. \"iol:iol\" or \"docker:docker\"). In this particular case, mapper keys are searched for partial matches where the map key matches the beginning of the provided EVE image. For example, \"iol:iol:i86bi_linux_l2:\" matches all IOL images that start with `i86bi_linux_l2` and maps them (by default) into `ioll2-xe`.\n\nAfter modification / adding more or different node type mappings to the exported map YAML, use the file via the `--mapper modified_map.yaml` flag.\n\nDisclaimer: There's certainly things out there which do not properly translate. If you encounter anything then raise an issue in the issue tracker and I'll look into it.\n\n> [!NOTE]\n> It is possible to change node types when importing. For example, you might want to change IOSv-L2 instances to IOLL2-XE instances by providing a custom import map. However, this does **NOT** change the device configuration of the imported nodes. So, if the configuration uses `GigabitEthernet0/4` in the original IOSv-L2 configuration then it is your responsibility to change this to `Ethernet1/0` for the configuration of the imported IOLL2-XE device. This can be easily done via a sed script or using a text editor and global search and replace. But this might be more involved depending on the original/target device type. See the [Change configurations](#change-configurations) section below for an example.\n\n## Usage\n\n```plain\n$ eve2cml -h\nusage: eve2cml [-h] [-V] [--level {debug,info,warning,error,critical}] [--stdout] [--nocolor] [--dump] [--mapper MAPPER] [-t] [--all] file_or_zip [file_or_zip ...]\n\nConvert UNL/XML topologies to CML2 topologies\n\npositional arguments:\n file_or_zip Path to either a UNL or ZIP with UNL file\n\noptional arguments:\n -h, --help show this help message and exit\n -V, --version show program's version number and exit\n --level {debug,info,warning,error,critical}\n specify the log level, default is warning\n --stdout do not store in files, print to stdout\n --nocolor no color log output\n --dump Dump the mapper as YAML\n --mapper MAPPER custom mapper YAML file\n -t, --text text output\n --all print all objects in text mode\n\nExample: eve2cml exportedlabs.zip\n\n$\n```\n\n## Change configurations\n\nWith a custom mapper file, node types can be modified while importing. For example, adding map entries like the following\n\n```yaml\n qemu:vios:\n image_def: null\n node_def: iol-xe\n override: false\n qemu:viosl2:\n image_def: null\n node_def: ioll2-xe\n override: false\n```\n\nto the mapper will change all IOSv instances to IOL-XE instances and all IOSv-L2 instances to IOLL2-XE instances. However, the day zero configuration files of those nodes will not be modified to match the now different interface names. In this particular case, where most of the configuration between IOSv and IOL-XE is identical *except for the interface names*, a simple sed script can do the trick. Here's how this can be done:\n\n1. create a sed script file with this content, filename `ios2iol-config`:\n\n ```plain\n s#GigabitEthernet0/0#Ethernet0/0#\n s#GigabitEthernet0/1#Ethernet0/1#\n s#GigabitEthernet0/2#Ethernet0/2#\n s#GigabitEthernet0/3#Ethernet0/3#\n s#GigabitEthernet0/4#Ethernet1/0#\n s#GigabitEthernet0/5#Ethernet1/1#\n s#GigabitEthernet0/6#Ethernet1/2#\n s#GigabitEthernet0/7#Ethernet1/3#\n s#GigabitEthernet0/8#Ethernet2/0#\n s#GigabitEthernet0/9#Ethernet2/1#\n s#GigabitEthernet0/10#Ethernet2/2#\n s#GigabitEthernet0/11#Ethernet2/3#\n s#GigabitEthernet0/12#Ethernet3/0#\n s#GigabitEthernet0/13#Ethernet3/1#\n s#GigabitEthernet0/14#Ethernet3/2#\n s#GigabitEthernet0/15#Ethernet3/3#\n ```\n\n2. dump the default / built-in mapper into a file (`--dump` option)\n3. modify the mapper to include the changes outlined above\n4. convert the topology with the modified map file (`--mapper` option)\n5. run `sed -f ios2iol-config lab.yaml >lab_with_configs_changed.yaml`\n\nThis will change all occurrences within the CML lab file from IOSv notation to IOL notation.\n\n## Contributing\n\nIf you have a more complete map file with additional or more specific node type mappings or if you have improved the code, fixed a bug or a typo or added a new feature then I more than welcome you to raise a pull request!\n\n## Issues\n\nIf you encounter any issues with the converter then please open a issue in the [GitHub issue tracker](https://github.com/CiscoDevNet/eve2cml/issues).\n\n### IOL interfaces\n\nThere's a known issue with the maximum number of interfaces defined in the shipping node definitions for IOL and IOL-L2. As for the released version of CML 2.7.0, the maximum number of interfaces is 16. If you have topologies which use more interfaces (`Ethernet4/0` and up) then you need to add the additional interfaces to the node definition in CML (Tools -> Node and image definitions -> IOL / IOL-L2). In the interface section, add the required interfaces and name them properly. Don't forget to click \"Update\" at the bottom when done.\n\nThis is fixed in the 2.7.1 release, once available.\n\nThe converter has now 32 interfaces defined in the mapper (`Ethernet0/0` to `Ethernet7/3`).\n\n### Known issues\n\nThere's a few things which are known to cause issues. Some of them might be addressable by code changes in the converter and/or changes on the CML side of things. And some might just not be possible at all.\n\n- Text objects in EVE can have a background color. The converter adds additional rectangles behind the text object in CML. It \"guesses\" the size of these rectangles. Those guesses are inaccurate.\n- Font (names) might not translate well. I think there's a general issue with serif vs. sans-serif mapping.\n- Images (PNGs) as part of a topology are ignored as there's no representation for them in CML.\n- More complex text boxes in EVE do not translate well into the more simple text annotation of CML. For color, size and font name, the first occurrence is used for the entire text object. Things like bullet lists etc. are completely ignored.\n- EVE multi-point networks are represented by unmanaged switches in CML. They have max 32 ports. That might not be enough.\n- Workbooks (\"tasks\") are not stored anywhere. Unclear at the moment, if and how to handle them.\n\nAlso check the [TODO](/TODO.md) file for additional things that will likely be added in subsequent releases.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A CLI tool to convert EVE-NG XML topology data into CML2 topology data as YAML",
"version": "0.1.2",
"project_urls": {
"Changelog": "https://github.com/ciscodevnet/eve2cml/blob/master/CHANGELOG.md",
"Homepage": "https://developer.cisco.com/modeling-labs",
"Issues": "https://github.com/ciscodevnet/eve2cml/issues",
"Repository": "https://github.com/ciscodevnet/eve2cml"
},
"split_keywords": [
"automation",
" network-programming",
" simulation",
" tools",
" virtualization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9b0793fc88f4e84d12d3ae984573e948c52bc95982391e656e7b5ea5a74b3434",
"md5": "337175a865ea936c650c01fe799c97c9",
"sha256": "787719f78359f688a8d5a54631683e3191c4f8919941b2c4d049de20a81a5a28"
},
"downloads": -1,
"filename": "eve2cml-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "337175a865ea936c650c01fe799c97c9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 24963,
"upload_time": "2024-10-07T17:52:53",
"upload_time_iso_8601": "2024-10-07T17:52:53.770874Z",
"url": "https://files.pythonhosted.org/packages/9b/07/93fc88f4e84d12d3ae984573e948c52bc95982391e656e7b5ea5a74b3434/eve2cml-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b2b3bfc2e709414dd0c3da85e1686d9fb0299237aea3d5eb4da67340870205a1",
"md5": "c0aae52f8ff8856c7262017a08fdcfe6",
"sha256": "5d4369fa8b4a23294783ed4ad0e00a4fb35e1c5476728a4c25e626ea83af0f83"
},
"downloads": -1,
"filename": "eve2cml-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "c0aae52f8ff8856c7262017a08fdcfe6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 205809,
"upload_time": "2024-10-07T17:52:55",
"upload_time_iso_8601": "2024-10-07T17:52:55.800944Z",
"url": "https://files.pythonhosted.org/packages/b2/b3/bfc2e709414dd0c3da85e1686d9fb0299237aea3d5eb4da67340870205a1/eve2cml-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-07 17:52:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ciscodevnet",
"github_project": "eve2cml",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "eve2cml"
}
JSON
