mirror of
https://github.com/Security-Onion-Solutions/securityonion.git
synced 2025-12-06 17:22:49 +01:00
update documentation of core functionality
This commit is contained in:
m0duspwnens
@@ -6,10 +6,20 @@
|
||||
# Elastic License 2.0.
|
||||
|
||||
"""
|
||||
Script to modify hardware parameters of a KVM virtual machine.
|
||||
Script for managing hardware configurations of KVM virtual machines. This script provides
|
||||
functionality to modify CPU, memory, and PCI device settings without manual XML editing
|
||||
or direct libvirt interaction.
|
||||
|
||||
The script offers three main configuration capabilities:
|
||||
1. CPU Management: Adjust virtual CPU count
|
||||
2. Memory Management: Modify memory allocation
|
||||
3. PCI Passthrough: Configure PCI device passthrough for direct hardware access
|
||||
|
||||
This script is designed to work with Security Onion's virtualization infrastructure and is typically
|
||||
used during VM provisioning and hardware reconfiguration tasks.
|
||||
|
||||
**Usage:**
|
||||
python so-kvm-modify-hardware.py -v <vm_name> [-c <cpu_count>] [-m <memory_amount>] [-p <pci_id>] [-p <pci_id> ...] [-s]
|
||||
so-kvm-modify-hardware -v <vm_name> [-c <cpu_count>] [-m <memory_amount>] [-p <pci_id>] [-p <pci_id> ...] [-s]
|
||||
|
||||
**Options:**
|
||||
-v, --vm Name of the virtual machine to modify.
|
||||
@@ -20,35 +30,99 @@ Script to modify hardware parameters of a KVM virtual machine.
|
||||
|
||||
**Examples:**
|
||||
|
||||
1. **Modify VM with Multiple PCI Devices:**
|
||||
1. **Modify CPU and Memory with Multiple PCI Devices:**
|
||||
|
||||
```bash
|
||||
python so-kvm-modify-hardware.py -v my_vm -c 4 -m 8192 -p 0000:00:1f.2 -p 0000:00:1f.3 -s
|
||||
so-kvm-modify-hardware -v vm1_sensor -c 4 -m 8192 -p 0000:00:1f.2 -p 0000:00:1f.3 -s
|
||||
```
|
||||
|
||||
This command modifies the VM named `my_vm`, setting the CPU count to 4, memory to 8192 MiB, and adds two PCI devices for passthrough (`0000:00:1f.2` and `0000:00:1f.3`). The VM is then started after modification due to the `-s` flag.
|
||||
This command modifies a VM with the following settings:
|
||||
- VM Name: `vm1_sensor`
|
||||
- Hardware Configuration:
|
||||
- CPUs: `4`
|
||||
- Memory: `8192` MiB
|
||||
- PCI Device Passthrough: `0000:00:1f.2`, `0000:00:1f.3`
|
||||
- The VM is started after modification due to the `-s` flag
|
||||
|
||||
2. **Modify VM with Single PCI Device:**
|
||||
2. **Add PCI Device Without Other Changes:**
|
||||
|
||||
```bash
|
||||
python so-kvm-modify-hardware.py -v my_vm -p 0000:00:1f.2
|
||||
so-kvm-modify-hardware -v vm2_master -p 0000:00:1f.4
|
||||
```
|
||||
|
||||
This command adds a single PCI device passthrough to the VM named `my_vm`.
|
||||
This command adds a single PCI device passthrough to the VM:
|
||||
- VM Name: `vm2_master`
|
||||
- PCI Device: `0000:00:1f.4`
|
||||
- Existing CPU and memory settings are preserved
|
||||
|
||||
3. **Modify VM Without Starting It:**
|
||||
3. **Update Resource Allocation:**
|
||||
|
||||
```bash
|
||||
python so-kvm-modify-hardware.py -v my_vm -c 2 -m 4096
|
||||
so-kvm-modify-hardware -v vm3_search -c 2 -m 4096
|
||||
```
|
||||
|
||||
This command sets the CPU count and memory for `my_vm` but does not start it afterward.
|
||||
This command updates only compute resources:
|
||||
- VM Name: `vm3_search`
|
||||
- CPUs: `2`
|
||||
- Memory: `4096` MiB
|
||||
- VM remains stopped after modification
|
||||
|
||||
4. **Add Multiple PCI Devices:**
|
||||
|
||||
```bash
|
||||
so-kvm-modify-hardware -v vm4_node -p 0000:00:1f.2 -p 0000:00:1f.3 -p 0000:00:1f.4 -s
|
||||
```
|
||||
|
||||
This command adds multiple PCI devices and starts the VM:
|
||||
- VM Name: `vm4_node`
|
||||
- PCI Devices: `0000:00:1f.2`, `0000:00:1f.3`, `0000:00:1f.4`
|
||||
- VM is started after modification
|
||||
|
||||
**Notes:**
|
||||
|
||||
- The `-p` or `--pci` option can be specified multiple times to pass through multiple PCI devices to the VM.
|
||||
- The PCI hardware IDs should be in the format `0000:00:1f.2`.
|
||||
- If the `-s` or `--start` flag is not provided, the VM will remain stopped after modification.
|
||||
- The script automatically stops the VM if it's running before making modifications.
|
||||
- At least one modification option (-c, -m, or -p) should be provided.
|
||||
- The PCI hardware IDs must be in the format `domain:bus:slot.function` (e.g., `0000:00:1f.2`).
|
||||
- Multiple PCI devices can be added by using the `-p` option multiple times.
|
||||
- Without the `-s` flag, the VM remains stopped after modification.
|
||||
- Existing hardware configurations are preserved if not explicitly modified.
|
||||
|
||||
**Description:**
|
||||
|
||||
The `so-kvm-modify-hardware` script modifies hardware parameters of KVM virtual machines using the following process:
|
||||
|
||||
1. **VM State Management:**
|
||||
- Connects to the local libvirt daemon
|
||||
- Stops the VM if it's currently running
|
||||
- Retrieves current VM configuration
|
||||
|
||||
2. **Hardware Configuration:**
|
||||
- Modifies CPU count if specified
|
||||
- Updates memory allocation if specified
|
||||
- Adds PCI device passthrough configurations if specified
|
||||
- All changes are made through libvirt XML configuration
|
||||
|
||||
3. **VM Redefinition:**
|
||||
- Applies the new configuration by redefining the VM
|
||||
- Optionally starts the VM if requested
|
||||
- Ensures clean shutdown and startup during modifications
|
||||
|
||||
4. **Error Handling:**
|
||||
- Validates all input parameters
|
||||
- Ensures proper XML structure
|
||||
- Provides detailed error messages for troubleshooting
|
||||
|
||||
**Exit Codes:**
|
||||
|
||||
- `0`: Success
|
||||
- `1`: An error occurred during execution
|
||||
|
||||
**Logging:**
|
||||
|
||||
- Logs are written to `/opt/so/log/hypervisor/so-kvm-modify-hardware.log`
|
||||
- Both file and console logging are enabled for real-time monitoring
|
||||
- Log entries include timestamps and severity levels
|
||||
- Detailed error messages are logged for troubleshooting
|
||||
|
||||
"""
|
||||
|
||||
|
||||
@@ -6,15 +6,112 @@
|
||||
# Elastic License 2.0.
|
||||
|
||||
"""
|
||||
Script to modify the NetworkManager config within a QCOW2 image.
|
||||
Script for modifying network configurations within QCOW2 virtual machine images. This script provides
|
||||
functionality to update NetworkManager settings, supporting both DHCP and static IP configurations
|
||||
without requiring the VM to be running.
|
||||
|
||||
Usage:
|
||||
python so-qcow2-modify-network.py -I <qcow2_image_path> -i <interface> (--dhcp4 | --static4 --ip4 <ip_address> --gw4 <gateway>) [--dns4 <dns_servers>] [--search4 <search_domain>]
|
||||
The script offers two main configuration modes:
|
||||
1. DHCP Configuration: Enable automatic IP address assignment
|
||||
2. Static IP Configuration: Set specific IP address, gateway, DNS servers, and search domains
|
||||
|
||||
Examples:
|
||||
python so-qcow2-modify-network.py -I /nsm/libvirt/images/sool9/sool9.qcow2 -i eth0 --static4 --ip4 192.168.1.10/24 --gw4 192.168.1.1 --dns4 192.168.1.1,8.8.8.8 --search4 example.local
|
||||
This script is designed to work with Security Onion's virtualization infrastructure and is typically
|
||||
used during VM provisioning and network reconfiguration tasks.
|
||||
|
||||
**Usage:**
|
||||
so-qcow2-modify-network -I <qcow2_image_path> -i <interface> (--dhcp4 | --static4 --ip4 <ip_address> --gw4 <gateway>)
|
||||
[--dns4 <dns_servers>] [--search4 <search_domain>]
|
||||
|
||||
**Options:**
|
||||
-I, --image Path to the QCOW2 image.
|
||||
-i, --interface Network interface to modify (e.g., eth0).
|
||||
--dhcp4 Configure interface for DHCP (IPv4).
|
||||
--static4 Configure interface for static IPv4 settings.
|
||||
--ip4 IPv4 address (e.g., 192.168.1.10/24). Required for static IPv4 configuration.
|
||||
--gw4 IPv4 gateway (e.g., 192.168.1.1). Required for static IPv4 configuration.
|
||||
--dns4 Comma-separated list of IPv4 DNS servers (e.g., 8.8.8.8,8.8.4.4).
|
||||
--search4 DNS search domain for IPv4.
|
||||
|
||||
**Examples:**
|
||||
|
||||
1. **Static IP Configuration with DNS and Search Domain:**
|
||||
|
||||
```bash
|
||||
so-qcow2-modify-network -I /nsm/libvirt/images/sool9/sool9.qcow2 -i eth0 --static4 \
|
||||
--ip4 192.168.1.10/24 --gw4 192.168.1.1 --dns4 192.168.1.1,192.168.1.2 --search4 example.local
|
||||
```
|
||||
|
||||
This command configures the network settings in the QCOW2 image with:
|
||||
- Static IPv4 configuration:
|
||||
- IP Address: `192.168.1.10/24`
|
||||
- Gateway: `192.168.1.1`
|
||||
- DNS Servers: `192.168.1.1`, `192.168.1.2`
|
||||
- DNS Search Domain: `example.local`
|
||||
|
||||
2. **DHCP Configuration:**
|
||||
|
||||
```bash
|
||||
so-qcow2-modify-network -I /nsm/libvirt/images/sool9/sool9.qcow2 -i eth0 --dhcp4
|
||||
```
|
||||
|
||||
This command configures the network interface to use DHCP for automatic IP address assignment.
|
||||
|
||||
3. **Static IP Configuration without DNS Settings:**
|
||||
|
||||
```bash
|
||||
so-qcow2-modify-network -I /nsm/libvirt/images/sool9/sool9.qcow2 -i eth0 --static4 \
|
||||
--ip4 192.168.1.20/24 --gw4 192.168.1.1
|
||||
```
|
||||
|
||||
This command sets only the basic static IP configuration:
|
||||
- IP Address: `192.168.1.20/24`
|
||||
- Gateway: `192.168.1.1`
|
||||
|
||||
**Notes:**
|
||||
|
||||
- When using `--static4`, both `--ip4` and `--gw4` options are required.
|
||||
- The script validates IP addresses, DNS servers, and interface names before making any changes.
|
||||
- DNS servers can be specified as a comma-separated list for multiple servers.
|
||||
- The script requires write permissions for the QCOW2 image file.
|
||||
- Interface names must contain only alphanumeric characters, underscores, and hyphens.
|
||||
|
||||
**Description:**
|
||||
|
||||
The `so-qcow2-modify-network` script modifies network configuration within a QCOW2 image using the following process:
|
||||
|
||||
1. **Image Access:**
|
||||
- Mounts the QCOW2 image using libguestfs
|
||||
- Locates and accesses the NetworkManager configuration directory
|
||||
|
||||
2. **Configuration Update:**
|
||||
- Reads the existing network configuration for the specified interface
|
||||
- Updates IPv4 settings based on provided parameters
|
||||
- Supports both DHCP and static IP configurations
|
||||
- Validates all input parameters before making changes
|
||||
|
||||
3. **File Management:**
|
||||
- Creates or updates the NetworkManager connection file
|
||||
- Maintains proper file permissions and format
|
||||
- Safely unmounts the image after changes
|
||||
|
||||
**Exit Codes:**
|
||||
|
||||
- `0`: Success
|
||||
- Non-zero: An error occurred during execution
|
||||
|
||||
**Logging:**
|
||||
|
||||
- Logs are written to `/opt/so/log/hypervisor/so-qcow2-modify-network.log`
|
||||
- Both file and console logging are enabled for real-time monitoring
|
||||
- Log entries include:
|
||||
- Timestamps in ISO 8601 format
|
||||
- Severity levels (INFO, WARNING, ERROR)
|
||||
- Detailed error messages for troubleshooting
|
||||
- Critical operations logged:
|
||||
- Network configuration changes
|
||||
- Image mount/unmount operations
|
||||
- Validation failures
|
||||
- File access errors
|
||||
|
||||
python so-qcow2-modify-network.py -I /nsm/libvirt/images/sool9/sool9.qcow2 -i eth0 --dhcp4
|
||||
"""
|
||||
|
||||
import argparse
|
||||
@@ -95,7 +192,6 @@ def update_ipv4_section(content, mode, ip=None, gateway=None, dns=None, search_d
|
||||
|
||||
return updated_content
|
||||
|
||||
# modify the network config file for the interface inside the qcow2 image
|
||||
def modify_network_config(image_path, interface, mode, ip=None, gateway=None, dns=None, search_domain=None):
|
||||
if not os.access(image_path, os.W_OK):
|
||||
raise PermissionError(f"Write permission denied for image file: {image_path}")
|
||||
|
||||
Reference in New Issue
Block a user