| Name | netunicorn-connector-containernet JSON |
| Version |
0.0.2
JSON |
| download |
| home_page | |
| Summary | ContainerNet connector for netunicorn |
| upload_time | 2023-11-17 09:45:39 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
netunicorn
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# netunicorn-connector-containernet
This is a netunicorn connector to a Containernet virtual infrastructure.
## User Guide
If your netunicorn installation has enabled Containernet connector, you can use it to create virtual infrastructure
with Containernet.
You would have an UncountableNodePool object, which (with `__next__` or `take` methods) generates virtual nodes.
You can assign your containers to these virtual nodes and netunicorn will create them in Containernet. You can safely
rename the nodes if needed, the provided name would be used by Containernet.
`WARNING`: the node name should be a valid Python identifier, as you can use it later in your network code to refer to the node.
If the node is not a valid Python identifier, the deployment would fail.
### Network configuration
During deployment, user can provide an arbitrary network configuration using the Containernet syntax:
1. The network configuration string should be provided in the 'network_definition' field of the deployment_context argument of `deploy` method.
2. The network configuration string should represent a JSON-serialized list of strings, where each string is a valid Python line of code for Containernet network configuration.
3. You can refer to your node names in network configuration.
4. You can safely assume, that in the local context of this Python code there exist a Containernet instance with a single controller called `net`.
5. You do not need to start the net execution
6. You do need to create corresponding switches and links for all nodes that should be connected.
7. If no network configuration is provided, the default network configuration is used. It creates a single switch and connects all nodes to it.
### Usage example
```python
# assuming you already created nodes with names "node1" and "node2"
import json
context = {
"network_definition": json.dumps([
"s1 = net.addSwitch('s1')",
"s2 = net.addSwitch('s2')",
"net.addLink(node1, s1)",
"net.addLink(node2, s2)",
"from mininet.link import TCLink",
"net.addLink(s1, s2, cls=TCLink, delay='100ms', bw=1)",
])
}
# netunicorn RemoteClient
client.deploy(experiment, 'experiment_name', deployment_context=context)
```
## Administrator guide
Containernet is a network emulator that uses Docker containers to emulate hosts and switches. It allows to create an arbitrary
network topology and set the network parameters for each link.
This package provides a netunicorn connector to Containernet.
### VM-based Installation
**WARNING:** Due to Containernet implementation, it requires to start Containernet Docker container in privileged mode, and
allows users to run arbitrary Python code inside this container. We **STRICTLY** recommend to run Containernet connector instance
inside an isolated virtual machine. In this scenario, the Containernet and corresponding connector are running on a virtual
machine and connector exposes a REST API to netunicorn. The Containernet connector should be started with a API KEY that should be
known to netunicorn instance administrators and specified in connector initialization parameters.
For all instructions below, we assume that you're using a Debian-like virtual machine with port
exposed to netunicorn server.
Inside the virtual machine:
1. Install python3-pip package: `apt install python3-pip`
2. Install openvswitch-switch package: `apt install openvswitch-switch`
3. Install Docker
4. Install connector with rest: `pip3 install netunicorn-connector-containernet[rest]`
5. Start the connector:
```bash
UVICORN_HOST=0.0.0.0 UVICORN_PORT=80 NETUNICORN_API_KEY=h34uyklfba uvicorn netunicorn.director.infrastructure.connectors.containernet.rest:app
```
- `UVICORN_HOST` - IP to bind to
- `UVICORN_PORT` - port to bind to
- `NETUNICORN_API_KEY` - API key used for authentication between netunicorn and the connector. Arbitrary string of symbols that should be shared.
On the netunicorn server:
1. Verify that `netunicorn-infrastructure` package is at least of version 0.3.1 (for REST communication)
2. Generate a configuration string for SimpleRESTConnector. This should be a string containing a JSON-serialized dictionary with the following fields:
- `url`: URL to the connector instance (in this example, exposed port on a virtual machine with Containernet connector instance)
- `api_key`: API key used for authentication between netunicorn and the connector (in this example, `h34uyklfba`)
- `init_params`: JSON object with parameters to be passed to the Containernet connector for initialization. Could be omitted.
- For Containernet, the next parameters are optional:
- `netunicorn_gateway`: netunicorn gateway endpoint
- Next parameters are optional:
- `docker_endpoint`: Docker socket. Default: `unix://var/run/docker.sock`
- `working_folder`: Folder to store temporary files. Default: `/tmp`
The simplest example of the configuration:
```json
{
"url": "http://192.168.0.3/",
"api_key": "h34uyklfba"
}
```
The example with additional parameters:
```json
{
"url": "http://192.168.0.3/",
"api_key": "h34uyklfba",
"init_params": {
"netunicorn_gateway": "http://192.168.0.2/netunicorn",
"docker_endpoint": "unix://var/run/docker.sock",
"working_folder": "/somefolder"
}
}
```
3. Correctly initialize a SimpleRESTConnector connector:
```yaml
netunicorn.infrastructure.connectors:
containernet:
enabled: true
module: "netunicorn.director.infrastructure.connectors.rest" # where to import from
class: "SimpleRESTConnector" # class name
config: '{"url": "http://192.168.0.3/", "api_key": "h34uyklfba"}' # configuration string from the previous step
```
Raw data
{
"_id": null,
"home_page": "",
"name": "netunicorn-connector-containernet",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "netunicorn",
"author": "",
"author_email": "Roman Beltiukov <rbeltiukov@ucsb.edu>",
"download_url": "https://files.pythonhosted.org/packages/86/9f/e0cdad3c11bd4783b24e6be3a0579196d90f755b937f195240ea61da2ec0/netunicorn-connector-containernet-0.0.2.tar.gz",
"platform": null,
"description": "# netunicorn-connector-containernet\nThis is a netunicorn connector to a Containernet virtual infrastructure.\n\n## User Guide\nIf your netunicorn installation has enabled Containernet connector, you can use it to create virtual infrastructure\nwith Containernet. \n\nYou would have an UncountableNodePool object, which (with `__next__` or `take` methods) generates virtual nodes.\nYou can assign your containers to these virtual nodes and netunicorn will create them in Containernet. You can safely\nrename the nodes if needed, the provided name would be used by Containernet.\n\n`WARNING`: the node name should be a valid Python identifier, as you can use it later in your network code to refer to the node.\nIf the node is not a valid Python identifier, the deployment would fail.\n\n### Network configuration\nDuring deployment, user can provide an arbitrary network configuration using the Containernet syntax:\n1. The network configuration string should be provided in the 'network_definition' field of the deployment_context argument of `deploy` method.\n2. The network configuration string should represent a JSON-serialized list of strings, where each string is a valid Python line of code for Containernet network configuration.\n3. You can refer to your node names in network configuration.\n4. You can safely assume, that in the local context of this Python code there exist a Containernet instance with a single controller called `net`.\n5. You do not need to start the net execution\n6. You do need to create corresponding switches and links for all nodes that should be connected. \n7. If no network configuration is provided, the default network configuration is used. It creates a single switch and connects all nodes to it.\n\n### Usage example\n```python\n# assuming you already created nodes with names \"node1\" and \"node2\"\nimport json\ncontext = {\n \"network_definition\": json.dumps([\n \"s1 = net.addSwitch('s1')\",\n \"s2 = net.addSwitch('s2')\",\n \"net.addLink(node1, s1)\",\n \"net.addLink(node2, s2)\",\n \"from mininet.link import TCLink\",\n \"net.addLink(s1, s2, cls=TCLink, delay='100ms', bw=1)\",\n ])\n}\n\n# netunicorn RemoteClient\nclient.deploy(experiment, 'experiment_name', deployment_context=context)\n```\n\n## Administrator guide\nContainernet is a network emulator that uses Docker containers to emulate hosts and switches. It allows to create an arbitrary\nnetwork topology and set the network parameters for each link.\n\nThis package provides a netunicorn connector to Containernet.\n\n### VM-based Installation\n\n**WARNING:** Due to Containernet implementation, it requires to start Containernet Docker container in privileged mode, and \nallows users to run arbitrary Python code inside this container. We **STRICTLY** recommend to run Containernet connector instance \ninside an isolated virtual machine. In this scenario, the Containernet and corresponding connector are running on a virtual \nmachine and connector exposes a REST API to netunicorn. The Containernet connector should be started with a API KEY that should be\nknown to netunicorn instance administrators and specified in connector initialization parameters.\n\nFor all instructions below, we assume that you're using a Debian-like virtual machine with port\nexposed to netunicorn server.\n\nInside the virtual machine:\n1. Install python3-pip package: `apt install python3-pip`\n2. Install openvswitch-switch package: `apt install openvswitch-switch`\n3. Install Docker\n4. Install connector with rest: `pip3 install netunicorn-connector-containernet[rest]`\n5. Start the connector:\n ```bash\n UVICORN_HOST=0.0.0.0 UVICORN_PORT=80 NETUNICORN_API_KEY=h34uyklfba uvicorn netunicorn.director.infrastructure.connectors.containernet.rest:app\n ```\n - `UVICORN_HOST` - IP to bind to\n - `UVICORN_PORT` - port to bind to\n - `NETUNICORN_API_KEY` - API key used for authentication between netunicorn and the connector. Arbitrary string of symbols that should be shared.\n\nOn the netunicorn server:\n1. Verify that `netunicorn-infrastructure` package is at least of version 0.3.1 (for REST communication)\n2. Generate a configuration string for SimpleRESTConnector. This should be a string containing a JSON-serialized dictionary with the following fields:\n - `url`: URL to the connector instance (in this example, exposed port on a virtual machine with Containernet connector instance)\n - `api_key`: API key used for authentication between netunicorn and the connector (in this example, `h34uyklfba`)\n - `init_params`: JSON object with parameters to be passed to the Containernet connector for initialization. Could be omitted.\n - For Containernet, the next parameters are optional:\n - `netunicorn_gateway`: netunicorn gateway endpoint\n - Next parameters are optional:\n - `docker_endpoint`: Docker socket. Default: `unix://var/run/docker.sock`\n - `working_folder`: Folder to store temporary files. Default: `/tmp` \n\n The simplest example of the configuration: \n ```json\n {\n \"url\": \"http://192.168.0.3/\",\n \"api_key\": \"h34uyklfba\"\n }\n ```\n\n The example with additional parameters:\n ```json\n {\n \"url\": \"http://192.168.0.3/\",\n \"api_key\": \"h34uyklfba\",\n \"init_params\": {\n \"netunicorn_gateway\": \"http://192.168.0.2/netunicorn\",\n \"docker_endpoint\": \"unix://var/run/docker.sock\",\n \"working_folder\": \"/somefolder\"\n }\n }\n ```\n\n3. Correctly initialize a SimpleRESTConnector connector:\n ```yaml\n netunicorn.infrastructure.connectors:\n containernet:\n enabled: true\n module: \"netunicorn.director.infrastructure.connectors.rest\" # where to import from\n class: \"SimpleRESTConnector\" # class name\n config: '{\"url\": \"http://192.168.0.3/\", \"api_key\": \"h34uyklfba\"}' # configuration string from the previous step\n ```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "ContainerNet connector for netunicorn",
"version": "0.0.2",
"project_urls": null,
"split_keywords": [
"netunicorn"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4f8fd8afd20432fce21d1b502896f95e1522559ab47be943e1ef4364669ea294",
"md5": "dd2128da2cd3bdea5377610a882e2b80",
"sha256": "c36aca08e751d889955ab804f4b5dc9866b06a1d3e5594e82f2453a77ff93381"
},
"downloads": -1,
"filename": "netunicorn_connector_containernet-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dd2128da2cd3bdea5377610a882e2b80",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 11856,
"upload_time": "2023-11-17T09:45:37",
"upload_time_iso_8601": "2023-11-17T09:45:37.967462Z",
"url": "https://files.pythonhosted.org/packages/4f/8f/d8afd20432fce21d1b502896f95e1522559ab47be943e1ef4364669ea294/netunicorn_connector_containernet-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "869fe0cdad3c11bd4783b24e6be3a0579196d90f755b937f195240ea61da2ec0",
"md5": "215988a7b87e902dffb32ec4b93c9c70",
"sha256": "7284cbddc05d449aea08fa664d66b44d5ed394fba99e1e5153fc681a56cb3fde"
},
"downloads": -1,
"filename": "netunicorn-connector-containernet-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "215988a7b87e902dffb32ec4b93c9c70",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 12739,
"upload_time": "2023-11-17T09:45:39",
"upload_time_iso_8601": "2023-11-17T09:45:39.096984Z",
"url": "https://files.pythonhosted.org/packages/86/9f/e0cdad3c11bd4783b24e6be3a0579196d90f755b937f195240ea61da2ec0/netunicorn-connector-containernet-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-17 09:45:39",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "netunicorn-connector-containernet"
}
