{"id":22393090,"url":"https://github.com/nemethf/epoxide","last_synced_at":"2026-02-07T12:02:10.833Z","repository":{"id":31653248,"uuid":"35218577","full_name":"nemethf/epoxide","owner":"nemethf","description":"A Modular Troubleshooting Framework for SDN","archived":false,"fork":false,"pushed_at":"2016-04-27T14:41:46.000Z","size":5703,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-07-27T07:04:46.046Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nemethf.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}},"created_at":"2015-05-07T12:24:55.000Z","updated_at":"2018-09-01T11:52:22.000Z","dependencies_parsed_at":"2022-09-10T07:01:41.423Z","dependency_job_id":null,"html_url":"https://github.com/nemethf/epoxide","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nemethf/epoxide","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nemethf%2Fepoxide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nemethf%2Fepoxide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nemethf%2Fepoxide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nemethf%2Fepoxide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nemethf","download_url":"https://codeload.github.com/nemethf/epoxide/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nemethf%2Fepoxide/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29194007,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-07T07:37:03.739Z","status":"ssl_error","status_checked_at":"2026-02-07T07:37:03.029Z","response_time":63,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2024-12-05T04:22:37.140Z","updated_at":"2026-02-07T12:02:10.821Z","avatar_url":"https://github.com/nemethf.png","language":"Emacs Lisp","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Epoxide\nA Modular Troubleshooting Framework for SDN\n\nEpoxide is an Emacs based modular framework, which can flexibly\ncombine network and software troubleshooting tools in a single\nplatform.  Epoxide does not try to be a complex troubleshooting\nsoftware that fully integrates all available tools, but rather a\nlightweight framework that allows the ad-hoc creation of tailor-made\ntesting methods from predefined building blocks to test\ntroubleshooting hypotheses.\n\nI. Pelle, T. L�vai, F. N�meth, and A. Guly�s: \"One Tool to Rule Them\nAll: A Modular Troubleshooting Framework for SDN (and other)\nNetworks\", ACM Sigcomm Symposium on SDN Research (SOSR), June 17-18,\n2015, Santa Clara, CA.\n[http://dx.doi.org/10.1145/2774993.2775014](http://dx.doi.org/10.1145/2774993.2775014)\n\n[SIGCOMM 2015 demo video](https://www.youtube.com/watch?v=HsiGFR0QirE)\n\n# Installation\n\nAdd the following lines to your emacs initialization file (~/.emacs):\n\n```\n  (package-initialize)\n  (add-to-list 'package-archives\n               '(\"epoxide\" . \"http://nemethf.github.io/epoxide/\") t)\n```\n\nThen install the `epoxide` package with M-x list-packages RET.\n\nTo utilize graph visualization install `graphviz` from your\ndistribution's package manager or from any other source.\n\n## Installation from the git repository\n\nFirst install COGRE either from the CEDET git repository or from the\npackage archive of Epoxide (see above), then add the following lines\nto your initialization file.\n\n```\n  (add-to-list 'load-path \"path-to-the-epoxide-repository/src\")\n  (autoload 'epo-mode \"epoxide\")\n  (add-to-list 'auto-mode-alist '(\"\\\\.tsg\\\\'\" . epoxide-tsg-mode))\n  (autoload 'tramp-mininet-setup \"tramp-mininet\")\n  (eval-after-load 'tramp '(tramp-mininet-setup))\n```\n\n# Introduction\n\nEpoxide is a tool built around the concept of connecting existing\nnetwork and software troubleshooting tools in a way that they can\ntransfer data among each other. To describe such scenarios we\nintroduce troubleshooting graphs.\n\n## Troubleshooting graphs\n\nTroubleshooting graphs (or TSGs in short) consist of nodes and\nlinks. Nodes are functional elements either implementing a wrapper for\nan external tool or providing entirely new functionality.  Links\nconnect nodes by relaying data between them.\n\n## Emacs based prototype\n\nWe created an [Emacs](https://www.gnu.org/software/emacs/) based\nprototype to illustrate how our concept works.  For defining TSGs we\nuse a\n[Click](http://www.read.cs.ucla.edu/click/docs/language)-inspired\nlanguage and store them in `.tsg` configuration files.  The nodes are\nimplemented in Emacs Lisp and we chose human readable text data to be\ntransfered between them.\n\nThe creation, execution and manipulation of TSGs are controlled by a\nframework that maps nodes and links to Emacs buffers and then helps\nthe data distribution among nodes.  Node buffers hold node specific\nattributes and potentially display state information; while link\nbuffers are the inputs and the outputs of the nodes containing human\nreadable text data (e.g. the output buffers of the Iperf wrapper node\ncontain the intact output of the wrapped tool).  The framework with\nthe help of its event scheduler is responsible to call the execution\nfunction of a node if one of its input buffers got modified,\nafterwards it is the responsibility of the execution function to\nprocess the input data, and to write into its output buffers.\n\nEpoxide offers:\n\n* *Easy extensibility*: framework and node functions are implemented\n   in separate Emacs Lisp files and the framework provides a\n   programming interface to node developers. This allows creating\n   third party node implementations and also external node\n   repositories.  Developers only have to write node initialization,\n   execution, and termination functions.  Optionally, they can add\n   documentation functions to provide information about node\n   configuration parameters.\n\n* *Context-aware buffer switching* keeps track of the created buffers\n   and provides support to move among them in an orderly fashion by\n   applying key combinations.  When multiple branches of the TSG are\n   available, possible choices are offered as a selectable list, or\n   they can be selected by the same key combination prefixed with the\n   output link's number.  Users can also switch to buffers associated\n   with the current Epoxide session by selecting from a list of buffer\n   names grouped together based on their types and positions in the\n   TSG.\n\n* *TSG visualization* offers a graph representation of the interpreted\n   `.tsg` file, navigation options for graph traversal, and quick\n   access to node and link buffers.\n\n* *Syntax highlighting and context-aware code completion* is provided\n   for `.tsg` files.  Additional, context-aware help is also shown\n   with the short documentation of the current node, in which the\n   currently typed parameter is highlighted.  Intelligent code\n   completion is offered: candidate lists are populated with node\n   classes and phrases from other buffers.\n\n* *Views* are special TSG elements that can create bundles of link and\n   node buffers to be displayed together by splitting the Emacs window\n   to different sub-windows.  In a complex TSG, views provide quick\n   access to a subset of the buffers.  Moreover, in case of a long\n   chain of nodes not only the final result is shown but every\n   intermediate partial result is also available for inspection in the\n   corresponding link buffer.\n\n* *Run-time node creation, reconfiguration and re-linking* provides\n   two possibilities to make modifications on a TSG that has already\n   been started.  The first one allows reinterpreting a modified\n   `.tsg` file and then reconfigures the TSG based on the\n   modifications.  The second one interactively guides the user to add\n   a new node or reconfigure existing nodes or links between them.\n\n* *Customization* of major Epoxide parameters is integrated in Emacs's\n   own customization interface and can be invoked via \u003ckbd\u003eM-x\n   customize group\u003c/kbd\u003e and then typing the `epoxide` keyword.\n\n# Usage\n\nHere we show how one can use Epoxide to test networks and extend it if\nthe available nodes aren't enough for the task at hand. If this is\nyour first time using Epoxide, you should read the article and watch\nthe video mentioned in the introduction for more in-depth information\nabout our tool. But do not be afraid, the learning curve of Epoxide is\nnot really steep if you are familiar with Emacs.\n\n## Demonstration\n\nTo better understand how Epoxide works, a simple example is presented\nthat takes you through the process of creating a troubleshooting\ngraph, executing it and making observations during its run.\n\n### The sample scenario\n\nLet's assume we have a host and want to test its connectivity to the\npublic internet. First we want to examine if connection can be\nestablished then we would like to measure the latency to some\nwell-known websites. To accomplish this, the simplest tool we can use\nis ping: it tells us whether the target website is available, and if\nso, the latency is displayed also.\n\nLet's further assume that we would like to mark those measurements\nwhere the round trip time exceeds a certain limit. To achieve this we\nwould need something that can process the output of ping.\n\n### Constructing the TSG file\n\nTo set up Epoxide to perform the required tests, we have to create a\nTSG file that describes the scenario as a troubleshooting\ngraph. Epoxide uses a Click-inspired language for describing such\ngraphs. Here we provide a simple one of that.  TSGs are recognized by\nEmacs/Epoxide as being stored in `.tsg` files. As an example take a\nlook at the content of [pingview.tsg](examples/pingview.tsg).\n\nIn this simple example let's split the definition into two main logical\nparts: the first is the description of nodes and views of the\ntroubleshooting graph and the second is the description of the links\nbetween them.\n\n```\n// Nodes\nping0 :: Ping(localhost, yahoo.com);\nping1 :: Ping(localhost, google.com);\nfilter0 :: Filter(time=\\([2-9][0-9]\\|[1-9][0-9]\\{2,\\}\\).*[0-9]* ms$);\nfilter1 :: Filter(time=\\([2-9][0-9]\\|[1-9][0-9]\\{2,\\}\\).*[0-9]* ms$);\nview :: View(1, 2);\n\n// Links\nping0 -\u003e filter0 -\u003e view;\nping1 -\u003e filter1 -\u003e [1]view;\n```\n\nWe define nodes for pinging yahoo.com and google.com and filters that\nhighlight response times longer or equal to 20 ms and a view that would\nserve as a means to provide a solution for the common need to see\nmultiple outputs aligned at once in a simple yet flexible way. Views\ncan be added to TSGs as they were nodes.\n\nA node is specified by its instance name (e.g. `ping0`) and its class\n(e.g. `Ping`). A class is assigned to the instance by using the `::`\noperator. Following the class declaration, node configuration parameters\ncan be specified in parentheses.\n\nLinks are then created that tie the nodes together. The output of a\nnode is connected to the input of another by adding the `-\u003e`\noperator. Nodes can have multiple in/outputs, to distinguish between\nthese write the number of the appropriate in/output in\nbrackets. Outputs should be written after the instance name of the\nnode, inputs before them. When using the 0th in/output, you can use\nthe simplification of omitting the brackets and numbers\naltogether. Multiple outputs can be linked to multiple inputs between\ntwo nodes by listing the appropriate numbers separating them with\na comma (e.g. `node1[1, 2, 3] -\u003e [4, 5, 2]node2` would link the 1st,\n2nd and 3rd output of `node1` to the 4th, 5th and 2nd input of `node2`\nrespectively). Note: you should list equal number of outputs and\ninputs.\n\nSince views are a special kind of nodes, one can use the `-\u003e` operator\nto link outputs of a node to a view. In case of a node's own buffer\ncontains the data of interest the `--\u003e` operator should be\nused. E.g. `node --\u003e view` means that the `node`'s own buffer will be\ndisplayed when switching to `view`.\n\nAn expression (instance declaration and linking) should always be\nterminated by a semicolon. A node instance declaration can be written\ninline in a linking expression. If you use a node only in one\nexpression you can omit the instance name part: by doing so the\nframework will generate a unique name for this node.\n\nIt is really easy to create new TSGs or modify existing ones due to\nthe convenient TSG editing features of Epoxide:\n\n* syntax highlighting that visually separates node classes and\n  instances,\n\n* Eldoc integration which provides short documentation for node\n  configuration parameters,\n\n* autocomplete support that brings intelligent code completion\n  capability,\n\n* and keyboard shortcuts for controlling the execution of the TSG and\n  the nodes.\n\nSince now we are familiar with the syntax of the TSG definition file\nwe can take a look at a simple execution scenario.\n\n### Executing the TSG\n\nExecuting a TSG describing the troubleshooting process itself is as\nsimple as opening the corresponding `.tsg` file. For starters let's\nsee an even simpler scenario then described before that uses only one\nPing and one Filter node. Let's open it now by issuing \u003ckbd\u003eC-x C-f\n~/.emacs.d/elpa/epoxide-\u003ccurrent version\u003e/examples/ping.tsg\nRET\u003c/kbd\u003e. Depending on your setup the execution starts automatically\nor you have to press \u003ckbd\u003eC-x C-e\u003c/kbd\u003e then hit \u003ckbd\u003ey\u003c/kbd\u003e at the\nconfirmation question to start the execution. (This behavior can be\ncustomized in the `epoxide` customization group by changing the value\nof the variable `epoxide-start-tsg-on-file-open`.) As the execution\nstarts, the Emacs frame splits horizontally and you can see the `.tsg`\nfile and the output of the last link in the TSG. Currently it is the\noutput of `ping` with lines emphasizing greater or equal than 20 ms\nresponse time.\n\nLet us suppose that we want to check the connectivity with a different\ntarget. It is really simple to do that with Epoxide. All you have to\ndo is modify the second parameter of the Ping node and reevaluate the\n`.tsg` file with \u003ckbd\u003eC-x C-e y\u003c/kbd\u003e. (Or you can move to the node's\nbuffer and change the parameter using the runtime node reconfiguration\noption as described later.)\n\n![epoxide-execution](doc/epoxide-exec.gif)\n\nAt this point we have a running TSG which we want to examine. The main\npurpose behind examining a TSG in details is to see the data-flow\nitself and to modify node variables on-the-fly. In order to aid\ntraversing a TSG, Epoxide can provide a graphical representation of\nthe TSG by pressing \u003ckbd\u003eM-x t\u003c/kbd\u003e or \u003ckbd\u003eC-x g\u003c/kbd\u003e. Nodes can be\neasily accessed from this view by clicking on their name or using key\nbindings (\u003ckbd\u003eC-x p\u003c/kbd\u003e and \u003ckbd\u003eC-x n\u003c/kbd\u003e).\n\nEvery node has its own buffer where a small help is provided and the\nnode's variables can be accessed by pressing \u003ckbd\u003ev\u003c/kbd\u003e; these\nvariables can be modified on-the-fly. Links between the nodes can be\naltered this way also.\n\nIt is also possible to navigate through the TSG via the links. Press\n\u003ckbd\u003eC-x n\u003c/kbd\u003e or \u003ckbd\u003eM-n\u003c/kbd\u003e to jump to the following link/node,\nand \u003ckbd\u003eC-x p\u003c/kbd\u003e or \u003ckbd\u003eM-p\u003c/kbd\u003e to the previous one. If you\nwant to jump back to the `.tsg` file, press \u003ckbd\u003eM-g e\u003c/kbd\u003e.\n\n![epoxide-navigation](doc/epoxide-nav.gif)\n\nOne might want to perform two pings at the same time. The\nmodifications of the TSG definition file to achieve this were discussed\nin the previous section. Comparison of the simple case and the one\nusing parallel pings is left to the reader.\n\nIf there are views in a TSG, the last one will be activated at the\nbeginning of the execution. Other views can be activated with the\nnumeric prefix \u003ckbd\u003eM-g v\u003c/kbd\u003e key binding, or you can cycle through\nthe defined views by pressing \u003ckbd\u003eM-p\u003c/kbd\u003e or \u003ckbd\u003eM-n\u003c/kbd\u003e as you\ncan see it in the animation.\n\n![epoxide-views](doc/epoxide-view.gif)\n\n## Implementing new nodes\n\nCurrently, Epoxide can only provide a limited number of predefined\nnodes, therefore, cannot cover every unique use-case. On such\noccasions, the functionality of Epoxide can be easily extended by\nimplementing new nodes. Nodes are written in [Emacs\nLisp](http://www.emacswiki.org/emacs/EmacsLisp) using some\nEpoxide-specific data structures which are well-documented in the\nsource code.\n\nTo implement a new node the following three Epoxide framework-specific\nfunctions have to be included in the node describing file:\n\n- `epoxide-\u003cnodename\u003e-start` is called when the node initializes,\n\n- `epoxide-\u003cnodename\u003e-exec` contains the function of the node, this is\n  the function called by the scheduler during TSG execution,\n\n- `epoxide-\u003cnodename\u003e-stop` is called when the node stops.\n\nIn these function names `\u003cnodename\u003e` should match the node definition\nfile name in all lower case letters.\n\nAdditional documentation-aiding functions can be added to a node:\n\n- `epoxide-\u003cnodename\u003e-input-info` provides documentation, value hints\n  and validation for input fields,\n\n- `epoxide-\u003cnodename\u003e-config-info` provides documentation, value hints\n  and validation for configuration fields,\n\n- `epoxide-\u003cnodename\u003e-output-info` provides documentation, value hints\n  and validation for output fields.\n\nExisting node definition files are collected in `src/nodes/` but this\nlocation can be customized by changing the value of the variable\n*epoxide-nodes-files-directory*. Node definition files should be Emacs\nLisp files and their names should start with a capital letter\n(e.g. *Nodename.el*).\n\nAs an example take a look at the [Ping node](src/nodes/Ping.el).\n\n# Keyboard shortcuts\n\nWe present the full extent of the specific Epoxide key bindings here.\n\nTroubleshooting Graph (TSG) execution:\n\n- \u003ckbd\u003eC-x C-e\u003c/kbd\u003e clears any previous information and restarts\n  execution of the TSG,\n\n- \u003ckbd\u003eC-c C-e\u003c/kbd\u003e restarts the execution of the TSG but keeps\n  previous information (this can be used for adding nodes and links to\n  the TSG).\n\nTSG modification:\n\n- \u003ckbd\u003eC-c C-a\u003c/kbd\u003e adds a new node to the TSG,\n- \u003ckbd\u003eC-c C-r\u003c/kbd\u003e restarts a node.\n\nNavigation, views, etc:\n\n- \u003ckbd\u003ev\u003c/kbd\u003e shows the Epoxide variable list,\n- \u003ckbd\u003ec\u003c/kbd\u003e customizes Epoxide variables,\n- \u003ckbd\u003eC-x C-b\u003c/kbd\u003e shows the Epoxide specific Ibuffer list,\n- \u003ckbd\u003eC-x g\u003c/kbd\u003e and \u003ckbd\u003eM-x t\u003c/kbd\u003e show the TSG visualization,\n- \u003ckbd\u003eM-g e\u003c/kbd\u003e shows the TSG file,\n- \u003ckbd\u003eC-x n\u003c/kbd\u003e jumps to the following node,\n- \u003ckbd\u003eC-x p\u003c/kbd\u003e jumps to the preceding node,\n- \u003ckbd\u003eC-c C-o\u003c/kbd\u003e shows every output buffers of the active node,\n- \u003ckbd\u003eM-n\u003c/kbd\u003e jumps to the next buffer in the TSG,\n- \u003ckbd\u003eM-p\u003c/kbd\u003e jumps to the previous buffer in the TSG,\n- \u003ckbd\u003eC-[1-9] M-g v\u003c/kbd\u003e activates View #[1-9],\n- \u003ckbd\u003eM-N\u003c/kbd\u003e activates the next View,\n- \u003ckbd\u003eM-P\u003c/kbd\u003e activates the previous View.\n\n# Acknowledgement\n\nThe research leading to these results has received funding from the\nEuropean Union Seventh Framework Programme under grant agreement\nNo. 619609.  See https://www.fp7-unify.eu/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnemethf%2Fepoxide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnemethf%2Fepoxide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnemethf%2Fepoxide/lists"}