Evengsdk

https://ttafsir.github.io/evengsdk/
Admin
Evengsdk is a Python library with command-line utilities to manage EVE-NG servers and network...
Tokens:12,862
Snippets:140
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### eve-ng lab start command

Source: https://ttafsir.github.io/evengsdk/cli_reference

Start all nodes within a lab.

```bash
eve-ng lab start eve-ng lab start --path /lab1
```

```bash
eve-ng lab start [OPTIONS]
```

```bash
--path TEXT
--help       Show this message and exit.
```

--------------------------------

### eve-ng node start usage

Source: https://ttafsir.github.io/evengsdk/cli_reference

Displays the usage and options for starting a lab node.

```bash
eve-ng node start [OPTIONS]
```

```bash
--path TEXT
-n, --node-id TEXT  [required]
--help              Show this message and exit.
```

--------------------------------

### Install Evengsdk with pip

Source: https://ttafsir.github.io/evengsdk

Install the eve-ng package from PyPI using pip.

```bash
pip install eve-ng
```

--------------------------------

### start_all_nodes(path)

Source: https://ttafsir.github.io/evengsdk/api_reference

Starts one or all nodes configured in a lab. For community edition, it uses a direct HTTP GET request; otherwise, it iterates over all nodes and starts each one.

```APIDOC
## start_all_nodes(path)

### Description
Start one or all nodes configured in a lab.

### Method
GET (community) or internal iteration (professional)

### Endpoint
/labs{path}/nodes/start (community)

### Parameters
#### Path Parameters
- **path** (str) - Required - Path to lab file (including parent folder)

### Response
#### Success Response (200)
- **status** (str) - Success or error
- **data** (object) - Response data
- **message** (str) - Response message

#### Response Example
{
  "status": "success",
  "data": {},
  "message": ""
}
```

--------------------------------

### Start All Nodes

Source: https://ttafsir.github.io/evengsdk/api_reference

Starts all nodes configured in a lab. Uses a direct API call for community versions or iterates through nodes for others.

```python
def start_all_nodes(self, path: str) -> Dict:
    """Start one or all nodes configured in a lab

    :param path: path to lab file (including parent folder)
    :type path: str
    """
    if self.is_community:
        url = f"/labs{self.normalize_path(path)}/nodes/start"
        return self.client.get(url)
    return self._update_nodes(path, "start")
```

--------------------------------

### start_node(path, node_id)

Source: https://ttafsir.github.io/evengsdk/api_reference

Starts a single node in a lab.

```APIDOC
## start_node(path, node_id)

### Description
Start single node in a lab.

### Method
GET

### Endpoint
/labs{path}/nodes/{node_id}/start

### Parameters
#### Path Parameters
- **path** (str) - Required - Path to lab file (including parent folder)
- **node_id** (str) - Required - ID of the node to start

### Response
#### Success Response (200)
- **status** (str) - Success or error
- **data** (object) - Response data
- **message** (str) - Response message

#### Response Example
{
  "status": "success",
  "data": {},
  "message": ""
}
```

--------------------------------

### eve-ng node start

Source: https://ttafsir.github.io/evengsdk/cli_reference

Starts a node in the lab.

```APIDOC
## eve-ng node start

### Description
Start node in lab.

### Method
CLI

### Command
`eve-ng node start [OPTIONS]`

### Options
- `--path TEXT` - Path to lab.
- `-n, --node-id TEXT` (required) - Node ID.
- `--help` - Show this message and exit.

### Example
`eve-ng node start -n 4`
```

--------------------------------

### eve-ng lab start

Source: https://ttafsir.github.io/evengsdk/cli_reference

Starts all nodes in a lab. Optionally specifies a lab path.

```APIDOC
## eve-ng lab start

### Description
Starts all nodes in a lab.

### Method
CLI

### Command
`eve-ng lab start`

### Parameters
#### Options
- `--path TEXT` - Optional - Path to the lab.

### Example
```
eve-ng lab start
eve-ng lab start --path /lab1
```
```

--------------------------------

### Static Configuration File Definition

Source: https://ttafsir.github.io/evengsdk/topology_builder

Example of configuring a node using a static file path.

```yaml
  nodes:
    - name: leaf01
      template: veos
      image: veos-4.22.0F
      node_type: qemu
      left: 50
      top: 135
      configuration:
        file: examples/configs/test_leaf01.cfg
```

--------------------------------

### Start Single Node

Source: https://ttafsir.github.io/evengsdk/api_reference

Starts a specific node in a lab by its ID.

```python
def start_node(self, path: str, node_id: str) -> Dict:
    """Start single node in a lab

    :param path: [description]
    :type path: str
    :param node_id: [description]
    :type node_id: str
    """
    url = "/labs" + self.normalize_path(path) + f"/nodes/{node_id}/start"
    return self.client.get(url)
```

--------------------------------

### eve-ng show-template usage

Source: https://ttafsir.github.io/evengsdk/cli_reference

Displays the usage and options for getting node template details.

```bash
eve-ng show-template [OPTIONS] TEMPLATE_NAME
```

```bash
--help  Show this message and exit.
```

--------------------------------

### Jinja Template Configuration

Source: https://ttafsir.github.io/evengsdk/topology_builder

Example of configuring a node using a Jinja template with variables sourced from a YAML file.

```yaml
    - name: leaf03
      template: veos
      image: veos-4.22.0F
      node_type: qemu
      left: 350
      top: 135
      configuration:
        template: base.j2
        vars: examples/data/leaf03.yml
```

--------------------------------

### get(url, *args, **kwargs)

Source: https://ttafsir.github.io/evengsdk/api_reference

Sends an HTTP GET request to the EVE-NG API. Uses the internal _make_request method to handle errors and JSON responses.

```APIDOC
## GET

### Description
Sends an HTTP GET request to the EVE-NG API.

### Method
GET

### Endpoint
(url)

### Parameters
#### Path Parameters
- **url** (str) - Required - The URL to send the request to.

### Request Example
```python
client.get(url, *args, **kwargs)
```

### Response
#### Success Response (200)
- Response object from requests library.

#### Response Example
```python
response = client.get(url)
```

### Error Handling
- Raises EvengHTTPError if the response contains a JSON error code and message.
- Raises HTTPError for other HTTP errors.
```

--------------------------------

### list_lab_networks

Source: https://ttafsir.github.io/evengsdk/api_reference

Gets all networks configured in a lab.

```APIDOC
## list_lab_networks

### Description
Gets all networks configured in a lab.

### Method
list_lab_networks

### Signature
list_lab_networks(self, path: str) -> Dict

### Parameters
- **path** (str) - Required - Path to lab file (include parent folder).

### Returns
- **Dict** - Networks data.
```

--------------------------------

### Get lab pictures

Source: https://ttafsir.github.io/evengsdk/api_reference

Retrieves one or all pictures configured in a lab.

```python
    def get_lab_pictures(self, path: str) -> Dict:
        """Get one or all pictures configured in a lab

        :param path: [description]
        :type path: str
        """
        url = f"/labs{self.normalize_path(path)}/pictures"
        return self.client.get(url)
```

--------------------------------

### eve-ng folder read

Source: https://ttafsir.github.io/evengsdk/cli_reference

Get folder details from EVE-NG host. Requires a folder path argument.

```APIDOC
## eve-ng folder read

### Description
Get folder details from EVE-NG host.

### Usage
```
eve-ng folder read [OPTIONS] FOLDER
```

### Arguments
- `FOLDER` - Required. Path to the folder.

### Options
- `--help` - Show this message and exit.

```

--------------------------------

### eve-ng user list command

Source: https://ttafsir.github.io/evengsdk/cli_reference

Command to list all EVE-NG users. Example: eve-ng user list

```bash
eve-ng user list [OPTIONS]
```

--------------------------------

### eve-ng show-template

Source: https://ttafsir.github.io/evengsdk/cli_reference

Gets EVE-NG node template details for a specified template name.

```APIDOC
## eve-ng show-template

### Description
Get EVE-NG node template details.

### Method
CLI

### Command
`eve-ng show-template [OPTIONS] TEMPLATE_NAME` n
### Options
- `--help` - Show this message and exit.

### Example
`eveng show-template veos`
```

--------------------------------

### eve-ng user create command

Source: https://ttafsir.github.io/evengsdk/cli_reference

Command to create a new EVE-NG user. Example: eve-ng user create -u user1 -p password1 -e -1 --role user --name "John Doe"

```bash
eve-ng user create [OPTIONS]
```

--------------------------------

### eve-ng folder read usage

Source: https://ttafsir.github.io/evengsdk/cli_reference

Gets folder details from the EVE-NG host using the folder read subcommand with a FOLDER argument.

```text
eve-ng folder read [OPTIONS] FOLDER
```

--------------------------------

### EvengClient.__init__

Source: https://ttafsir.github.io/evengsdk/api_reference

Initializes a new EvengClient instance with connection parameters and logging configuration.

```APIDOC
## EvengClient.__init__

### Description
Initializes a new EvengClient instance with connection parameters and logging configuration.

### Method
Constructor

### Parameters
- **host** (str) - Optional - The EVE-NG host address.
- **protocol** (str) - Optional - The protocol to use (http or https). Defaults to "http".
- **log_file** (str) - Optional - Path to a log file for logging.
- **log_level** (str) - Optional - Log level for the logger. Defaults to "INFO".
- **port** (int) - Optional - The port number for the EVE-NG API.
- **disable_insecure_warnings** (bool) - Optional - If True, disables insecure request warnings.
- **ssl_verify** (bool) - Optional - If True, verifies SSL certificates. Defaults to True.

### Request Example
python
client = EvengClient(host="192.168.1.1", protocol="https", port=443, ssl_verify=False)


### Response
No return value.
```

--------------------------------

### add_node(self, path, template, delay=0, name='', node_type='qemu', top=38, left=43, console='telnet', config='Unconfigured', ethernet=None, serial=None, image=None, icon=None, ram=None, cpu=None, nvram=None, idlepc=None, slot='')

Source: https://ttafsir.github.io/evengsdk/api_reference

Creates a node and adds it to a lab. This method is documented in the source but the full implementation is not shown in the provided text.

```APIDOC
## add_node(self, path, template, delay=0, name='', node_type='qemu', top=38, left=43, console='telnet', config='Unconfigured', ethernet=None, serial=None, image=None, icon=None, ram=None, cpu=None, nvram=None, idlepc=None, slot='')

### Description
Creates a node and adds it to a lab. This method is documented in the source but the full implementation is not shown in the provided text.

### Parameters
- **path** (str) - Required - The lab path
- **template** (str) - Required - The node template
- **delay** (int) - Optional - Delay in seconds (default: 0)
- **name** (str) - Optional - Node name (default: '')
- **node_type** (str) - Optional - Node type (default: 'qemu')
- **top** (int) - Optional - Top margin (default: 38)
- **left** (int) - Optional - Left margin (default: 43)
- **console** (str) - Optional - Console type (default: 'telnet')
- **config** (str) - Optional - Configuration (default: 'Unconfigured')
- **ethernet** (optional) - Optional - Ethernet settings
- **serial** (optional) - Optional - Serial settings
- **image** (optional) - Optional - Image name
- **icon** (optional) - Optional - Icon name
- **ram** (optional) - Optional - RAM size
- **cpu** (optional) - Optional - CPU count
- **nvram** (optional) - Optional - NVRAM size
- **idlepc** (optional) - Optional - Idle PC value
- **slot** (str) - Optional - Slot (default: '')

### Source Code
Not provided in the source text.
```

--------------------------------

### Build a topology with EvengClient

Source: https://ttafsir.github.io/evengsdk

Create a lab, add a management network, add nodes, connect nodes to the management network, create point-to-point links, and logout. Uses HTTPS with SSL verification disabled and disables insecure warnings for self-signed certificates.

```python
from evengsdk.client import EvengClient


client = EvengClient("10.246.32.254", log_file="test.log", ssl_verify=False, protocol="https")
client.disable_insecure_warnings()  # disable warnings for self-signed certificates
client.login(username="admin", password="eve")
client.set_log_level("DEBUG")

# create a lab
lab = {"name": "test_lab", "description": "Test Lab", "path": "/"}
resp = client.api.create_lab(**lab)
if resp['status'] == "success":
  print("lab created successfully.")

# we need the lab path to create objects in the lab
lab_path = f"{lab['path']}{lab['name']}.unl"

# create management network
mgmt_cloud = {"name": "eve-mgmt", "network_type": "pnet1"}
client.api.add_lab_network(lab_path, **mgmt_cloud)

# create Nodes
nodes = [
    {"name": "leaf01", "template": "veos", "image": "veos-4.22.0F", "left": 50},
    {"name": "leaf02", "template": "veos", "image": "veos-4.22.0F", "left": 200},
]
for node in nodes:
    client.api.add_node(lab_path, **node)

# connect nodes to management network
mgmt_connections = [
    {"src": "leaf01", "src_label": "Mgmt1", "dst": "eve-mgmt"},
    {"src": "leaf02", "src_label": "Mgmt1", "dst": "eve-mgmt"}
]
for link in mgmt_connections:
    client.api.connect_node_to_cloud(lab_path, **link)

# create p2p links
p2p_links = [
    {"src": "leaf01", "src_label": "Eth1", "dst": "leaf02", "dst_label": "Eth1"},
    {"src": "leaf01", "src_label": "Eth1", "dst": "leaf02", "dst_label": "Eth2"},
]
for link in p2p_links:
    client.api.connect_node_to_node(lab_path, **link)

client.logout()
```

--------------------------------

### Basic API usage with EvengClient

Source: https://ttafsir.github.io/evengsdk

Create an EvengClient, login to an EVE-NG server, and list node templates via the client.api interface.

```python
from evengsdk.client import EvengClient
from pprint import pprint

client = EvengClient("10.246.32.254", log_file="test.log")
client.login(username="admin", password="eve")

resp = client.api.list_node_templates()
```

--------------------------------

### __init__(self, client)

Source: https://ttafsir.github.io/evengsdk/api_reference

Initializes the EVE-NG API wrapper object with a client instance. It retrieves the server status to determine the version and whether the server is a community edition.

```APIDOC
## __init__(self, client)

### Description
Initializes the EVE-NG API wrapper object with a client instance. It retrieves the server status to determine the version and whether the server is a community edition.

### Method
Constructor

### Parameters
- **client** (evengsdk.client.EvengClient) - Required - The EvengClient object for managing REST calls
- **timeout** (int, optional) - Required - Connection timeout in seconds, defaults to 30

### Source Code
```python
def __init__(self, client):
    """EVE-NG API wrapper object

    :param client: the EvengClient object for managing REST calls
    :type client: evengsdk.client.EvengClient
    :param timeout: connection timeout in seconds, defaults to 30
    :type timeout: int, optional
    """
    self.client = client
    self.log = client.log
    self.version = None
    self.supports_multi_tenants = False
    self.is_community = True

    status = self.get_server_status()
    self.version = status["data"]["version"]

    if self.version and "pro" in self.version.lower():
        self.is_community = False
```
```

--------------------------------

### Enable Node Configuration

Source: https://ttafsir.github.io/evengsdk/api_reference

Enables a node's startup configuration by sending a PUT request.

```python
    def enable_node_config(self, path: str, node_id: str) -> Dict:
        """Enable a node's startup config

        :param path: path to lab file (include parent folder)
        :type path: str
        :param node_id: node ID to enable config for
        :type node_id: str
        """
        url = "/labs" + f"{self.normalize_path(path)}/nodes/{node_id}"
        return self.client.put(url, data=json.dumps({"id": node_id, "config": 1}))
```

--------------------------------

### list_lab_links

Source: https://ttafsir.github.io/evengsdk/api_reference

Gets all remote endpoints for both ethernet and serial interfaces.

```APIDOC
## list_lab_links

### Description
Gets all remote endpoints for both ethernet and serial interfaces.

### Method
list_lab_links

### Signature
list_lab_links(self, path: str) -> Dict

### Parameters
- **path** (str) - Required - Path to lab file (include parent folder).

### Returns
- **Dict** - Links data.
```

--------------------------------

### EvengClient.login

Source: https://ttafsir.github.io/evengsdk/api_reference?q=

Initiates login to the EVE-NG host and creates an API wrapper object.

```APIDOC
## EvengClient.login

### Description
Initiates login to the EVE-NG host using the provided username and password. Accepts additional arguments for the request.Session object. Raises EvengLoginError on unsuccessful login.

### Method
Method

### Parameters
- **username** (str) - Required - EVE-NG login username.
- **password** (str) - Required - EVE-NG login password.
- **args** - Optional - Additional positional arguments for the request.
- **kwargs** - Optional - Additional keyword arguments for the request, except "data" key.

### Request Example
```python
client.login(username="admin", password="secret")
```

### Response
No return value. On success, sets the `username` attribute and creates an `EvengApi` instance.
```

--------------------------------

### Get lab topology

Source: https://ttafsir.github.io/evengsdk/api_reference

Retrieves the topology configuration for a given lab path.

```python
    def get_lab_topology(self, path: str) -> Dict:
        """Get the lab topology

        :param path: [description]
        :type path: str
        """
        url = "/labs" + self.normalize_path(path) + "/topology"
        return self.client.get(url)
```

--------------------------------

### Get node interfaces

Source: https://ttafsir.github.io/evengsdk/api_reference

Retrieves the configured interfaces for a specific node in a lab.

```python
    def get_node_interfaces(self, path: str, node_id: int) -> Dict:
        """Get configured interfaces from a node.

        :param path: lab path
        :type path: str
        :param node_id: node id in lab
        :type node_id: int
        """
        url = "/labs" + self.normalize_path(path) + f"/nodes/{node_id}/interfaces"
        return self.client.get(url)
```

--------------------------------

### eve-ng lab create command

Source: https://ttafsir.github.io/evengsdk/cli_reference

Create a new lab with specified metadata.

```bash
eve-ng lab create --name lab1 --author "John Doe" --description "My lab"
```

```bash
eve-ng lab create [OPTIONS]
```

```bash
--path TEXT         folder to create lab in
--name TEXT         lab name  [required]
--author TEXT       lab author
--description TEXT  lab description
--version TEXT      lab version
--help              Show this message and exit.
```

--------------------------------

### eve-ng lab create-from-topology command

Source: https://ttafsir.github.io/evengsdk/cli_reference

Create a new lab from a topology file.

```bash
eveng lab create-from-topology --topology examples/test_topology.yml
```

```bash
eve-ng lab create-from-topology [OPTIONS]
```

```bash
-t, --topology PATH      Toplogy file to import  [required]
-d, --template-dir PATH  Template directory
--help                   Show this message and exit.
```

--------------------------------

### get_lab_topology

Source: https://ttafsir.github.io/evengsdk/api_reference

Retrieves the lab topology. Sends a GET request to /labs/{path}/topology.

```APIDOC
## GET /labs/{path}/topology

### Description
Get the lab topology.

### Method
GET

### Endpoint
/labs/{path}/topology

### Parameters
#### Path Parameters
- **path** (str) - Required - Lab path

### Response
Returns a dictionary containing the API response.
```

--------------------------------

### Get lab picture details

Source: https://ttafsir.github.io/evengsdk/api_reference

Retrieves details for a single picture identified by its ID.

```python
    def get_lab_picture_details(self, path: str, picture_id: int) -> Dict:
        """Retrieve single picture

        :param path: [description]
        :type path: str
        :param picture_id: [description]
        :type picture_id: int
        """
        url = "/labs" + self.normalize_path(path) + f"/pictures/{picture_id}"
        return self.client.get(url)
```

--------------------------------

### Export node configuration

Source: https://ttafsir.github.io/evengsdk/api_reference

Saves the startup-config into the lab file for a specific node.

```python
    def export_node(self, path: str, node_id: int) -> Dict:
        """Export node configuration. Exporting means
        saving the startup-config into the lab file.

        :param path: lab path
        :type path: str
        :param node_id: node ID for to export config from
        :type node_id: int
        """
        url = "/labs" + f"{self.normalize_path(path)}/nodes/{node_id}/export"
        return self.client.put(url)
```

--------------------------------

### login(username, password, *args, **kwargs)

Source: https://ttafsir.github.io/evengsdk/api_reference

Initiates login to the EVE-NG host. Accepts args and kwargs for the request.Session object, except the 'data' key. Raises EvengLoginError for unsuccessful logins.

```APIDOC
## login(username, password, *args, **kwargs)

### Description
Initiates login to the EVE-NG host. Accepts args and kwargs for the request.Session object, except the 'data' key.

### Method
POST

### Endpoint
{url_prefix}/auth/login

### Parameters
#### Path Parameters
- **username** (str) - Required - EVE-NG login username.
- **password** (str) - Required - EVE-NG login password.

#### Request Body
- **username** (str) - Required - EVE-NG login username.
- **password** (str) - Required - EVE-NG login password.
- **html5** (bool) - Required - HTML5 flag.

### Request Example
```json
{
  "username": "admin",
  "password": "secret",
  "html5": true
}
```

### Response
#### Success Response (200)
- Response contains "logged in" in JSON.

#### Response Example
```json
{
  "logged in": true
}
```

### Error Handling
- Raises EvengLoginError for unsuccessful logins.
```

--------------------------------

### EvengApi.get_user(username)

Source: https://ttafsir.github.io/evengsdk/api_reference

Gets user details. Returns an empty dictionary if the user does not exist.

```APIDOC
## GET /users/{username}

### Description
Get user details. Returns empty dictionary if the user does not exist.

### Method
GET

### Endpoint
/users/{username}

### Parameters
#### Path Parameters
- **username** (string) - Required - Username to retrieve details for.

### Response
#### Success Response (200)
- **data** (object) - Contains user details.

#### Response Example
{
  "data": {
    "username": "user1",
    "role": "admin"
  }
}
```

--------------------------------

### eve-ng list-network-types command

Source: https://ttafsir.github.io/evengsdk/cli_reference

List all available network types in EVE-NG.

```bash
eveng list-network-types
```

```bash
eve-ng list-network-types [OPTIONS]
```

```bash
--output [json|text|table]
--help                      Show this message and exit.
```

--------------------------------

### Update Nodes Action

Source: https://ttafsir.github.io/evengsdk/api_reference

Internal helper to perform an action (stop, start, wipe) on all nodes in a lab.

```python
def _update_nodes(
    self, path: str, action: Literal["stop", "start", "wipe"]
) -> Dict:
    resp = self.list_nodes(path)
    action_method = getattr(self, f"{action}_node")
    if resp["data"]:
        results = []
        for node_id, _ in resp["data"].items():
            res = action_method(path, node_id)
            results.append(res)
        return self._extract_recursive_statuses(results)
    return resp
```

--------------------------------

### get_lab_picture_details

Source: https://ttafsir.github.io/evengsdk/api_reference

Retrieves a single picture from a lab. Sends a GET request to /labs/{path}/pictures/{picture_id}.

```APIDOC
## GET /labs/{path}/pictures/{picture_id}

### Description
Retrieve single picture.

### Method
GET

### Endpoint
/labs/{path}/pictures/{picture_id}

### Parameters
#### Path Parameters
- **path** (str) - Required - Lab path
- **picture_id** (int) - Required - Picture ID

### Response
Returns a dictionary containing the API response.
```

--------------------------------

### eve-ng user options

Source: https://ttafsir.github.io/evengsdk/cli_reference

Displays the help options for the user command.

```bash
--help  Show this message and exit.
```

--------------------------------

### get_lab_pictures

Source: https://ttafsir.github.io/evengsdk/api_reference

Retrieves one or all pictures configured in a lab. Sends a GET request to /labs/{path}/pictures.

```APIDOC
## GET /labs/{path}/pictures

### Description
Get one or all pictures configured in a lab.

### Method
GET

### Endpoint
/labs/{path}/pictures

### Parameters
#### Path Parameters
- **path** (str) - Required - Lab path

### Response
Returns a dictionary containing the API response.
```

--------------------------------

### upload_node_config

Source: https://ttafsir.github.io/evengsdk/api_reference

Uploads a node's startup config.

```APIDOC
## PUT /labs/{path}/configs/{node_id}

### Description
Uploads a node's startup config.

### Method
PUT

### Endpoint
/labs/{path}/configs/{node_id}

### Parameters
#### Path Parameters
- **path** (str) - Required - Path to lab file (include parent folder)
- **node_id** (str) - Required - Node ID to upload config for

#### Request Body
- **id** (str) - Required - Node ID
- **data** (str) - Required - Configuration string
- **cfsid** (str) - Optional - Configset ID (pro version)

### Response
#### Success Response (200)
- **data** (object) - Upload result

#### Response Example
{
  "data": {}
}
```

--------------------------------

### eve-ng folder options

Source: https://ttafsir.github.io/evengsdk/cli_reference

Options for the eve-ng folder command, which only shows --help.

```text
  --help  Show this message and exit.
```

--------------------------------

### eve-ng lab read

Source: https://ttafsir.github.io/evengsdk/cli_reference

Gets EVE-NG lab details. Optionally specifies a path and output format.

```APIDOC
## eve-ng lab read

### Description
Gets EVE-NG lab details.

### Method
CLI

### Command
`eve-ng lab read`

### Parameters
#### Options
- `--path TEXT` - Optional - Path to the lab.
- `--output [json|text]` - Optional - Output format.

### Example
```
eve-ng lab read
eve-ng lab read --path /folder/to/lab.unl
```
```

--------------------------------

### eve-ng user create options

Source: https://ttafsir.github.io/evengsdk/cli_reference

Available options for creating an EVE-NG user.

```bash
-n, --name TEXT           User's name
-u, --username TEXT       login username  [required]
-p, --password TEXT       login password
-e, --expiration INTEGER  expiration date for accout (UNIX timestamp). -1
                            means never expire. default is -1.
-r, --role TEXT           user role
--email TEXT              user email
--help                    Show this message and exit.
```

--------------------------------

### EvengClient.login

Source: https://ttafsir.github.io/evengsdk/api_reference

Initiates login to the EVE-NG host. Accepts args and kwargs for the request.Session object, except the "data" key.

```APIDOC
## EvengClient.login

### Description
Initiates login to the EVE-NG host. Accepts args and kwargs for the request.Session object, except the "data" key.

### Method
Method

### Parameters
- **username** (str) - Required - The EVE-NG login username.
- **password** (str) - Required - The EVE-NG login password.
- **args** - Optional - Additional positional arguments for the request.Session.post method.
- **kwargs** - Optional - Additional keyword arguments for the request.Session.post method. The "data" key is ignored.

### Request Example
python
client.login(username="admin", password="secret")


### Response
No return value. On success, sets the username and creates an EvengApi wrapper object. Raises EvengLoginError on unsuccessful login.
```

--------------------------------

### normalize_path

Source: https://ttafsir.github.io/evengsdk/api_reference

Normalizes a lab path by ensuring it starts with a slash, resolving it, adding the .unl extension, and URL-encoding each part.

```APIDOC
## normalize_path

### Description
Normalizes a lab path by ensuring it starts with a slash, resolving it, adding the .unl extension, and URL-encoding each part.

### Method
normalize_path

### Signature
normalize_path(self, path: str) -> str

### Parameters
- **path** (str) - Required - The path to normalize.

### Returns
- **str** - The normalized path.
```

--------------------------------

### Create Lab CLI Command

Source: https://ttafsir.github.io/evengsdk/topology_builder

Command to instantiate a lab from a topology file, optionally specifying a template directory.

```bash
eve-ng lab create-from-topology -t examples/test_topology.yml --template-dir examples/templates
```

--------------------------------

### eve-ng lab import command

Source: https://ttafsir.github.io/evengsdk/cli_reference

Import a lab from a ZIP archive.

```bash
eve-ng lab import [OPTIONS]
```

```bash
--src PATH     source path to ZIP lab file
--folder TEXT  folder on EVE-NG to import lab to
--help       Show this message and exit.
```

--------------------------------

### get_node_interfaces

Source: https://ttafsir.github.io/evengsdk/api_reference

Retrieves the configured interfaces from a node. Sends a GET request to /labs/{path}/nodes/{node_id}/interfaces.

```APIDOC
## GET /labs/{path}/nodes/{node_id}/interfaces

### Description
Get configured interfaces from a node.

### Method
GET

### Endpoint
/labs/{path}/nodes/{node_id}/interfaces

### Parameters
#### Path Parameters
- **path** (str) - Required - Lab path
- **node_id** (int) - Required - Node id in lab

### Response
Returns a dictionary containing the API response.
```

--------------------------------

### Get Node by Name

Source: https://ttafsir.github.io/evengsdk/api_reference

Retrieves a single node object from a lab by searching for its name within the node list.

```python
    def get_node_by_name(self, path: str, name: str) -> Dict:
        """Retrieve single node from lab by name

        :param path: path to lab file (include parent folder)
        :type path: str
        :param name: node name
        :type name: str
        """
        r = self.list_nodes(path)
        node_data = r["data"]
        if node_data:
            return next((v for _, v in node_data.items() if v["name"] == name), None)
        return
```

--------------------------------

### export_all_nodes method in evengsdk/api.py

Source: https://ttafsir.github.io/evengsdk/api_reference

Saves the startup-config of one or all nodes into the lab file.

```python
def export_all_nodes(self, path: str) -> Dict:
    """Export one or all nodes configured in a lab.
    Exporting means saving the startup-config into
    the lab file.

    :param path: [description]
    :type path: str
    """
    url = "/labs" + self.normalize_path(path) + "/nodes/export"
    return self.client.put(url)
```

--------------------------------

### eve-ng node create usage

Source: https://ttafsir.github.io/evengsdk/cli_reference

Displays the usage and options for creating a lab node.

```bash
eve-ng node create [OPTIONS]
```

```bash
--name TEXT                     node name
--node-type [iol|qemu|dynamips]
--template TEXT                 node template to create node from
                                [required]
--image TEXT                    image to boot node with
--ethernet INTEGER              number of ethernet interfaces.
--serial INTEGER                number of serial interfaces.
--console-type [telnet|vnc]     number of serial interfaces.
--ram INTEGER                   RAM for node
--cpu INTEGER                   CPU count for node
--path TEXT
--help                          Show this message and exit.
```

--------------------------------

### eve-ng CLI options

Source: https://ttafsir.github.io/evengsdk/cli_reference?q=

Available global options for the eve-ng command.

```bash
--version             Show the version and exit.
--host TEXT           [required]
--username TEXT       [default: (current user); required]
--password TEXT       [required]
--port INTEGER        HTTP port to connect to. Default is 80
--protocol TEXT       Protocol to use. Default is http
--insecure TEXT       Disable SSL
--verify BOOLEAN      Verify SSL certificate
--debug / --no-debug  Enables or disables debug mode.
-v, --verbose         Enables verbosity.
--help                Show this message and exit.
```

--------------------------------

### create_lab(self, name, path='/', author='', body='', version='1.0', description='', scripttimeout=600, lock=0, tenant='')

Source: https://ttafsir.github.io/evengsdk/api_reference

Creates a new lab on the EVE-NG server. It sends a POST request to the /labs endpoint with lab configuration data.

```APIDOC
## create_lab(self, name, path='/', author='', body='', version='1.0', description='', scripttimeout=600, lock=0, tenant='')

### Description
Create a new lab.

### Method
POST

### Endpoint
/labs

### Parameters
#### Request Body
- **name** (str) - Required - name of the lab
- **path** (str) - Optional - path to lab file on EVE-NG server, defaults to "/"
- **author** (str) - Optional - lab author, defaults to ""
- **body** (str) - Optional - long description for lab, defaults to ""
- **version** (str) - Optional - lab version. Defaults to "1.0"
- **description** (str) - Optional - short description, defaults to ""
- **scripttimeout** (int) - Optional - value in seconds used for the “Configuration Export” and “Boot from exported configs” operations, defaults to 600
- **lock** (int) - Optional - set lab as readonly. Defaults to 0

### Request Example
{
  "path": "/",
  "name": "lab_name",
  "version": "1.0",
  "author": "",
  "description": "",
  "body": "",
  "lock": 0,
  "scripttimeout": 600
}

### Response
#### Success Response (200)
- **response** (object) - The response from the server

#### Response Example
{
  "success": true
}
```

--------------------------------

### stop_all_nodes(path)

Source: https://ttafsir.github.io/evengsdk/api_reference

Stops one or all nodes configured in a lab. For community edition, it uses a direct HTTP GET request; otherwise, it iterates over all nodes and stops each one.

```APIDOC
## stop_all_nodes(path)

### Description
Stop one or all nodes configured in a lab.

### Method
GET (community) or internal iteration (professional)

### Endpoint
/labs{path}/nodes/stop (community)

### Parameters
#### Path Parameters
- **path** (str) - Required - Path to lab file (including parent folder)

### Response
#### Success Response (200)
- **status** (str) - Success or error
- **data** (object) - Response data
- **message** (str) - Response message

#### Response Example
{
  "status": "success",
  "data": {},
  "message": ""
}
```

--------------------------------

### enable_node_config

Source: https://ttafsir.github.io/evengsdk/api_reference

Enables a node's startup config.

```APIDOC
## PUT /labs/{path}/nodes/{node_id}

### Description
Enables a node's startup config.

### Method
PUT

### Endpoint
/labs/{path}/nodes/{node_id}

### Parameters
#### Path Parameters
- **path** (str) - Required - Path to lab file (include parent folder)
- **node_id** (str) - Required - Node ID to enable config for

#### Request Body
- **id** (str) - Required - Node ID
- **config** (int) - Required - Set to 1 to enable

### Response
#### Success Response (200)
- **data** (object) - Enable result

#### Response Example
{
  "data": {}
}
```

--------------------------------

### wipe_all_nodes(path)

Source: https://ttafsir.github.io/evengsdk/api_reference

Wipes one or all nodes configured in a lab. Wiping deletes all user config, including startup-config, VLANs, and so on. The next start will rebuild node from selected image.

```APIDOC
## wipe_all_nodes(path)

### Description
Wipe one or all nodes configured in a lab. Wiping deletes all user config, included startup-config, VLANs, and so on. The next start will rebuild node from selected image.

### Method
GET (community) or internal iteration (professional)

### Endpoint
/labs{path}/nodes/wipe (community)

### Parameters
#### Path Parameters
- **path** (str) - Required - Path to lab file (including parent folder)


### Response
#### Success Response (200)
- **status** (str) - Success or error
- **data** (object) - Response data
- **message** (str) - Response message

#### Response Example
{
  "status": "success",
  "data": {},
  "message": ""
}
```

--------------------------------

### wipe_node(path, node_id)

Source: https://ttafsir.github.io/evengsdk/api_reference

Wipes a single node configured in a lab. Wiping deletes all user config, including startup-config, VLANs, and so on. The next start will rebuild node from selected image.

```APIDOC
## wipe_node(path, node_id)

### Description
Wipe single node configured in a lab. Wiping deletes all user config, included startup-config, VLANs, and so on. The next start will rebuild node from selected image.

### Method
GET

### Endpoint
/labs{path}/nodes/{node_id}/wipe

### Parameters
#### Path Parameters
- **path** (str) - Required - Path to lab file (including parent folder)
- **node_id** (int) - Required - ID of the node to wipe

### Response
#### Success Response (200)
- **status** (str) - Success or error
- **data** (object) - Response data
- **message** (str) - Response message

#### Response Example
{
  "status": "success",
  "data": {},
  "message": ""
}
```

--------------------------------

### create_lab method

Source: https://ttafsir.github.io/evengsdk/api_reference

Creates a new lab on the EVE-NG server with specified metadata. Supports multi-tenant configurations if enabled.

```python
def create_lab(
    self,
    name: str,
    path: str = "/",
    author: str = "",
    body: str = "",
    version: str = "1.0",
    description: str = "",
    scripttimeout: int = 600,
    lock: int = 0,
    tenant: str = "",
) -> Dict:
    """Create a new lab

    :param name: name of the lab
    :type name: str
    :param path: path to lab file on EVE-NG server, defaults to "/"
    :type path: str, optional
    :param author: lab author, defaults to ""
    :type author: str, optional
    :param body: long description for lab, defaults to ""
    :type body: str, optional
    :param version: lab version. Defaults to "1.0"
    :type version: str, optional
    :param description: short description, defaults to ""
    :type description: str, optional
    :param scripttimeout: value in seconds used for the
            “Configuration Export” and “Boot from exported configs”
            operations, defaults to 600
    :type scripttimeout: int, optional
    :param lock: set lab as as readonly. Defaults to 0
    :type lock: int, optional
    :param tenant: tenant (username) to create lab for, defaults to ""
    :type tenant: str, optional
    """
    data = {
        "path": path,
        "name": name,
        "version": version,
        "author": author,
        "description": description,
        "body": body,
        "lock": lock,
        "scripttimeout": scripttimeout,
    }

    url = "/labs"
    if self.supports_multi_tenants:
        existing_user = self.get_user(tenant)
        if existing_user:
            url += "{tenant}/"
    return self.client.post(url, data=json.dumps(data))
```

--------------------------------

### eve-ng user edit command

Source: https://ttafsir.github.io/evengsdk/cli_reference

Command to update an existing EVE-NG user. Example: eve-ng user edit -u user1 --name "Jane Doe"

```bash
eve-ng user edit [OPTIONS]
```

--------------------------------

### eve-ng folder list options

Source: https://ttafsir.github.io/evengsdk/cli_reference

Options for the folder list command, including the --output flag for selecting the output format.

```text
  --output [json|text|table]
  --help                      Show this message and exit.
```

--------------------------------

### HTTP Error Handling and Request Methods

Source: https://ttafsir.github.io/evengsdk/api_reference

Handles JSON-formatted HTTP error responses from the EVE-NG API and provides standard HTTP request wrappers for POST, GET, PUT, PATCH, and DELETE operations.

```python
if hasattr(r, "json"):
    try:
        err_code = r.json().get("code")
    except json.JSONDecodeError:
        err_code = r.text
    try:
        err_msg = r.json().get("message")
    except json.JSONDecodeError:
        err_msg = r.text
    raise EvengHTTPError("Error: {} {}".format(err_code, err_msg))

# Other HTTP errors for which we don't have a JSON response
r.raise_for_status()

def post(self, url: str, *args, **kwargs):
    return self._make_request("POST", url, *args, **kwargs)

def get(self, url: str, *args, **kwargs):
    return self._make_request("GET", url, *args, **kwargs)

def put(self, url: str, *args, **kwargs):
    return self._make_request("PUT", url, *args, **kwargs)

def patch(self, url: str, *args, **kwargs):
    return self._make_request("PATCH", url, *args, **kwargs)

def delete(self, url: str, *args, **kwargs):
    return self._make_request("DELETE", url, *args, **kwargs)
```

--------------------------------

### eve-ng user create usage

Source: https://ttafsir.github.io/evengsdk/cli_reference?q=

Usage syntax for creating an EVE-NG user.

```bash
eve-ng user create [OPTIONS]

```

--------------------------------

### eve-ng node config usage

Source: https://ttafsir.github.io/evengsdk/cli_reference

Displays the usage and options for uploading device configurations.

```bash
eve-ng node config [OPTIONS]
```

```bash
--path TEXT
-n, --node-id TEXT  [required]
-s, --src PATH      config file to upload
-c, --config TEXT   config to upload
--help              Show this message and exit.
```

--------------------------------

### enable_node_config method in evengsdk/api.py

Source: https://ttafsir.github.io/evengsdk/api_reference

Enables the startup configuration for a specific node within a lab.

```python
def enable_node_config(self, path: str, node_id: str) -> Dict:
    """Enable a node's startup config

    :param path: path to lab file (include parent folder)
    :type path: str
    :param node_id: node ID to enable config for
    :type node_id: str
    """
    url = "/labs" + f"{self.normalize_path(path)}/nodes/{node_id}"
    return self.client.put(url, data=json.dumps({"id": node_id, "config": 1}))
```

--------------------------------

### eve-ng list-node-templates usage

Source: https://ttafsir.github.io/evengsdk/cli_reference

Displays the usage and options for listing EVE-NG node templates.

```bash
eve-ng list-node-templates [OPTIONS]
```

```bash
--output [json|text|table]
--help                      Show this message and exit.
```

--------------------------------

### eve-ng user list options

Source: https://ttafsir.github.io/evengsdk/cli_reference

Available options for listing EVE-NG users.

```bash
--output [json|text|table]
--help                      Show this message and exit.
```

--------------------------------

### eve-ng lab show-active command

Source: https://ttafsir.github.io/evengsdk/cli_reference

Display the currently active lab.

```bash
eve-ng lab show-active
```

```bash
eve-ng lab show-active [OPTIONS]
```

```bash
--help  Show this message and exit.
```

--------------------------------

### Initialize EVE-NG API Wrapper

Source: https://ttafsir.github.io/evengsdk/api_reference

Initializes the API wrapper object with a client and determines if the server is a Community or Pro edition based on the version string.

```python
def __init__(self, client):
    """EVE-NG API wrapper object

    :param client: the EvengClient object for managing REST calls
    :type client: evengsdk.client.EvengClient
    :param timeout: connection timeout in seconds, defaults to 30
    :type timeout: int, optional
    """
    self.client = client
    self.log = client.log
    self.version = None
    self.supports_multi_tenants = False
    self.is_community = True

    status = self.get_server_status()
    self.version = status["data"]["version"]

    if self.version and "pro" in self.version.lower():
        self.is_community = False
```

--------------------------------

### eve-ng main options

Source: https://ttafsir.github.io/evengsdk/cli_reference

Options for the eve-ng command, including connection parameters and debug/verbose flags.

```text
  --version             Show the version and exit.
  --host TEXT           [required]
  --username TEXT       [default: (current user); required]
  --password TEXT       [required]
  --port INTEGER        HTTP port to connect to. Default is 80
  --protocol TEXT       Protocol to use. Default is http
  --insecure TEXT       Disable SSL
  --verify BOOLEAN      Verify SSL certificate
  --debug / --no-debug  Enables or disables debug mode.
  -v, --verbose         Enables verbosity.
  --help                Show this message and exit.
```

--------------------------------

### eve-ng list-user-roles usage

Source: https://ttafsir.github.io/evengsdk/cli_reference

Displays the usage and options for listing EVE-NG user roles.

```bash
eve-ng list-user-roles [OPTIONS]
```

```bash
--output [json|text|table]
--help                      Show this message and exit.
```
Tokens:
Raw