# Clones

## Table of Contents

1. [Overview](#1-overview)
2. [Browsing Clones](#2-browsing-clones)
3. [Creating a Clone](#3-creating-a-clone)
4. [Viewing Clone Details](#4-viewing-clone-details)
5. [Managing Clone Lifecycle](#5-managing-clone-lifecycle)
6. [Updating a Clone](#6-updating-a-clone)
7. [Deleting a Clone](#7-deleting-a-clone)
8. [Networking](#8-networking)
9. [Domain Controller Settings](#9-domain-controller-settings)

***

## 1. Overview

**Clones** are virtual machines created from VM images within the Axilon system. They allow you to provision isolated environments for testing, development, or production use. Each clone is linked to a configuration and a VM image, and can optionally be connected to a Windows domain controller.

The Clones page provides full lifecycle management: create, start, stop, suspend, resume, reboot, snapshot, and delete.

***

## 2. Browsing Clones

### Steps

1. Click **Clones** in the sidebar.
2. The page displays a paginated table (5 items per page by default).
3. The table auto-refreshes every 5 seconds to show real-time status updates.

### Table Columns

| Column              | What It Shows                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------- |
| **Name**            | Clone name with machine indicator and status badge.                                         |
| **Primary Machine** | The source/host machine the clone runs on.                                                  |
| **Configuration**   | The linked configuration name (clickable).                                                  |
| **VM Image**        | The VM image the clone was created from.                                                    |
| **Clone Status**    | Color-coded status badge (Running, Stopped, Paused, Crashed, etc.) with failover indicator. |
| **CPU / RAM**       | Resource allocation shown as "X vCPUs / Y GB". Hover for usage vs. limits.                  |
| **Created By**      | The user who created the clone.                                                             |
| **Created At**      | Creation date.                                                                              |
| **Actions**         | Context-sensitive action menu (see [Section 5](#5-managing-clone-lifecycle)).               |

### Filtering

Use the filters above the table to narrow results:

| Filter            | Description              |
| ----------------- | ------------------------ |
| **Configuration** | Filter by configuration. |
| **Machine**       | Filter by host machine.  |
| **Status**        | Filter by clone status.  |

***

## 3. Creating a Clone

> **Required role:** Global Admin

### Steps

1. Go to **Clones**.
2. Click **"Create Clone"** in the page header.
3. Fill out the form sections:

### Basic Information

| Field             | Required | Rules                         | Notes                                                                            |
| ----------------- | :------: | ----------------------------- | -------------------------------------------------------------------------------- |
| **Name**          |    Yes   | Minimum 5 characters          | A unique name for the clone.                                                     |
| **Description**   |    Yes   | 1--128 characters             | Describe the clone's purpose.                                                    |
| **Machine**       |    No    | --                            | Optionally link to an existing machine.                                          |
| **Configuration** |    Yes   | Must be a valid configuration | Select the backup/restore configuration. Filtered by machine if one is selected. |

### VM Image and Ports

| Field                | Required | Notes                                                              |
| -------------------- | :------: | ------------------------------------------------------------------ |
| **VM Image**         |    Yes   | Select from available clone images.                                |
| **Port Ranges**      |    No    | Define ranges of ports to expose (protocol, start port, end port). |
| **Individual Ports** |    No    | Define specific ports to expose (protocol, guest port).            |

Port values must be between 1 and 65535. End port must be greater than or equal to the start port.

### Resources

| Field                | Required | Notes                                                                                                                   |
| -------------------- | :------: | ----------------------------------------------------------------------------------------------------------------------- |
| **CPU Allocated**    |    Yes   | Use the slider to select the number of vCPUs (minimum 1). The maximum is determined by the system's resource limits.    |
| **Memory Allocated** |    Yes   | Use the slider to select RAM in MB (minimum 2048 MB / 2 GB). The maximum is determined by the system's resource limits. |

The sliders display current allocation vs. available resources (e.g., "4 vCPUs out of 16 vCPUs").

### Network

| Field       | Required | Notes                                 |
| ----------- | :------: | ------------------------------------- |
| **Network** |    Yes   | Select from available clone networks. |

If the selected network is a **Bridge** type, additional fields appear:

| Field       | Required | Rules                                                   |
| ----------- | :------: | ------------------------------------------------------- |
| **Address** |    Yes   | Valid IPv4 with CIDR notation (e.g., 192.168.1.100/24). |
| **DNS**     |    Yes   | At least one valid IPv4 DNS address.                    |
| **Gateway** |    Yes   | Valid IPv4 address.                                     |
| **MAC**     |    Yes   | Valid MAC address (e.g., aa:bb:cc:dd:ee:ff).            |

### Domain Controller Settings

See [Section 9](#9-domain-controller-settings) for full details.

4. Click **"Submit"**.
5. On success, a confirmation notification appears and the clone begins provisioning.

***

## 4. Viewing Clone Details

### Steps

1. In the Clones table, click **View** in the row's actions menu, or click the clone name.
2. The details page shows:

### Clone Statistics

| Stat              | Description                                                        |
| ----------------- | ------------------------------------------------------------------ |
| **Status**        | Current status with failover indicator.                            |
| **Configuration** | Linked configuration name (clickable to scroll to config section). |
| **Resources**     | vCPUs and RAM with tooltip showing usage vs. limits.               |
| **Created By**    | The user who created the clone.                                    |
| **Created At**    | Creation date.                                                     |
| **Updated At**    | Last modification date.                                            |

### RDP Credentials

When the clone is **Running**, this section displays remote desktop connection credentials:

* RDP username
* RDP password
* Connection information

If credentials cannot be retrieved, an error alert is shown.

### Image Information

* VM Image name used to create the clone.

### Network Information

* Network type (Bridge or NAT).
* IP address and network name.
* For Bridge networks: static IP, DNS servers, gateway, and MAC address.
* Port mappings (if configured).

### Machine Information

* **Clone Machine** details: name, status, and properties.
* **Primary Machine** details: the host machine name, status, and properties.

### Configuration Information

* Full details of the linked configuration.

***

## 5. Managing Clone Lifecycle

The actions available for a clone depend on its current status.

### Available Actions by Status

| Status                 | Available Actions                                                   |
| ---------------------- | ------------------------------------------------------------------- |
| **Running**            | Stop, Suspend, Reboot, Create Snapshot, Resync, Start/Stop Failover |
| **Stopped**            | Start, Delete                                                       |
| **Paused / Suspended** | Resume, Delete                                                      |
| **Crashed**            | Start, Delete                                                       |

### Action Descriptions

| Action              | What It Does                                                          |
| ------------------- | --------------------------------------------------------------------- |
| **Start**           | Powers on the clone VM.                                               |
| **Stop**            | Gracefully shuts down the clone VM.                                   |
| **Suspend**         | Pauses the clone, preserving its current memory state.                |
| **Resume**          | Resumes a suspended clone from its saved state.                       |
| **Reboot**          | Restarts the clone VM.                                                |
| **Create Snapshot** | Captures the clone's current state as a VM snapshot.                  |
| **Resync**          | Re-synchronizes the clone with its configuration.                     |
| **Start Failover**  | Activates failover mode for the clone.                                |
| **Stop Failover**   | Deactivates failover mode.                                            |
| **Delete**          | Permanently removes the clone (see [Section 7](#7-deleting-a-clone)). |

> **Required role:** Global Admin for all management actions.

***

## 6. Updating a Clone

> **Required role:** Global Admin

### Steps

1. Navigate to the clone's details page.
2. Click **"Update"** in the header.
3. The form is pre-filled with the clone's current values. Modify any fields as needed.
4. Click **"Submit"**.
5. A confirmation notification appears on success.

***

## 7. Deleting a Clone

> **Required role:** Global Admin

### Steps

1. In the Clones table, click **Delete** in the row's actions menu.
2. Confirm the deletion in the dialog.
3. A confirmation notification appears on success.

> **Note:** The clone must be in a **Stopped**, **Paused**, or **Crashed** state before it can be deleted.

***

## 8. Networking

Clones support two network types:

### NAT (Network Address Translation)

* The clone shares the host machine's network connection.
* Port forwarding is configured through the port ranges and individual ports fields.
* No additional network configuration is needed.

### Bridge

* The clone gets its own IP address on the physical network.
* You must provide:
  * **Address** in CIDR notation (e.g., 192.168.1.100/24)
  * At least one **DNS** server IP
  * A **Gateway** IP
  * A **MAC** address

***

## 9. Domain Controller Settings

Clones can optionally be joined to a Windows domain or configured as a domain controller.

### Connecting to a Domain Controller

Enable the **"Connect to DC"** checkbox to reveal domain connection settings. You have two options:

#### Option A: Select an Existing DC Machine

1. Enable **"Connect to DC"**.
2. Select a **Domain Controller** machine from the dropdown (lists available DC clones in the system).
3. Provide a **DC Script** -- a PowerShell or batch script that configures the domain join. The script must contain the `<DC_IP_ADDRESS>` placeholder, which is replaced with the actual DC IP at runtime.

#### Option B: Specify DC Credentials Manually

1. Enable **"Connect to DC"**.
2. Fill in all four credential fields:

| Field                 | Required | Description                                        |
| --------------------- | :------: | -------------------------------------------------- |
| **Domain Hostname**   |    Yes   | The hostname or FQDN of the domain controller.     |
| **Domain Name**       |    Yes   | The domain name (e.g., company.local).             |
| **DC Admin Username** |    Yes   | An administrator account on the domain controller. |
| **DC Admin Password** |    Yes   | The password for the admin account.                |

> **Note:** If you provide any one of the four credential fields, all four are required.

### Sysprep

When **"Connect to DC"** is enabled, an additional **"Sysprep"** checkbox appears. Enable it to run Windows Sysprep as part of the domain join process (used for Windows image preparation).

### Configuring as a Domain Controller

Enable the **"Is Domain Controller"** checkbox to designate this clone as a domain controller. A **DC Script** is required to set up the DC role.

### DC Script Variables

The DC script must include the `<DC_IP_ADDRESS>` placeholder when connecting to a DC. This is replaced at runtime with the actual IP address of the selected domain controller.