CSEC_PUBLIC/securityonion
1
0
Fork 0
mirror of https://github.com/Security-Onion-Solutions/securityonion.git synced 2025-12-06 09:12:45 +01:00
Code Issues Packages Projects Releases Wiki Activity

update documentation of core functionality

Browse Source
This commit is contained in:
m0duspwnens
2025-01-18 10:45:10 -05:00
parent 64c9230423
commit 9db3cd901c
4 changed files with 444 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

154
salt/_modules/qcow2.py
View File

@@ -1,5 +1,23 @@
#!py
# Copyright Security Onion Solutions LLC and/or licensed to Security Onion Solutions LLC under one
# or more contributor license agreements. Licensed under the Elastic License 2.0 as shown at
# https://securityonion.net/license; you may not use this file except in compliance with the
# Elastic License 2.0.
"""
Salt module for managing QCOW2 image configurations and VM hardware settings. This module provides functions
for modifying network configurations within QCOW2 images and adjusting virtual machine hardware settings.
It serves as a Salt interface to the so-qcow2-modify-network and so-kvm-modify-hardware scripts.
The module offers two main capabilities:
1. Network Configuration: Modify network settings (DHCP/static IP) within QCOW2 images
2. Hardware Configuration: Adjust VM hardware settings (CPU, memory, PCI passthrough)
This module is intended to work with Security Onion's virtualization infrastructure and is typically
used in conjunction with salt-cloud for VM provisioning and management.
"""
import logging
import subprocess
import shlex
@@ -13,24 +31,67 @@ def __virtual__():
def modify_network_config(image, interface, mode, ip4=None, gw4=None, dns4=None, search4=None):
'''
Wrapper function to call so-qcow2-modify-network
Usage:
salt '*' qcow2.modify_network_config image=<path> interface=<iface> mode=<mode> [ip4=<addr>] [gw4=<addr>] [dns4=<servers>] [search4=<domain>]
:param image: Path to the QCOW2 image.
:param interface: Network interface to modify (e.g., 'eth0').
:param mode: 'dhcp4' or 'static4'.
:param ip4: IPv4 address with CIDR notation (e.g., '192.168.1.10/24'). Required for static configuration.
:param gw4: IPv4 gateway (e.g., '192.168.1.1'). Required for static configuration.
:param dns4: Comma-separated list of IPv4 DNS servers (e.g., '8.8.8.8,8.8.4.4').
:param search4: DNS search domain for IPv4.
Options:
image
Path to the QCOW2 image file that will be modified
interface
Network interface name to configure (e.g., 'eth0')
mode
Network configuration mode, either 'dhcp4' or 'static4'
ip4
IPv4 address with CIDR notation (e.g., '192.168.1.10/24')
Required when mode='static4'
gw4
IPv4 gateway address (e.g., '192.168.1.1')
Required when mode='static4'
dns4
Comma-separated list of IPv4 DNS servers (e.g., '8.8.8.8,8.8.4.4')
Optional for both DHCP and static configurations
search4
DNS search domain for IPv4 (e.g., 'example.local')
Optional for both DHCP and static configurations
:return: A dictionary with the result of the script execution.
Examples:
1. **Configure DHCP:**
```bash
salt '*' qcow2.modify_network_config image='/nsm/libvirt/images/sool9/sool9.qcow2' interface='eth0' mode='dhcp4'
```
This configures eth0 to use DHCP for IP assignment
CLI Example:
2. **Configure Static IP:**
```bash
salt '*' qcow2.modify_network_config image='/nsm/libvirt/images/sool9/sool9.qcow2' interface='eth0' mode='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 sets a static IP configuration with DNS servers and search domain
.. code-block:: bash
Notes:
- The QCOW2 image must be accessible and writable by the salt minion
- The image should not be in use by a running VM when modified
- Network changes take effect on next VM boot
- Requires so-qcow2-modify-network script to be installed
salt '*' qcow2.modify_network_config image='/nsm/libvirt/images/sool9/sool9.qcow2' interface='eth0' mode='static4' ip4='192.168.1.10/24' gw4='192.168.1.1' dns4='192.168.1.1,8.8.8.8' search4='example.local'
Description:
This function modifies network configuration within a QCOW2 image file by executing
the so-qcow2-modify-network script. It supports both DHCP and static IPv4 configuration.
The script mounts the image, modifies the network configuration files, and unmounts
safely. All operations are logged for troubleshooting purposes.
Exit Codes:
0: Success
1: Invalid parameters or configuration
2: Image access or mounting error
3: Network configuration error
4: System command error
255: Unexpected error
Logging:
- All operations are logged to the salt minion log
- Log entries are prefixed with 'qcow2 module:'
- Error conditions include detailed error messages and stack traces
- Success/failure status is logged for verification
'''
cmd = ['/usr/sbin/so-qcow2-modify-network', '-I', image, '-i', interface]
@@ -69,22 +130,71 @@ def modify_network_config(image, interface, mode, ip4=None, gw4=None, dns4=None,
def modify_hardware_config(vm_name, cpu=None, memory=None, pci=None, start=False):
'''
Wrapper function to call so-kvm-modify-hardware
Usage:
salt '*' qcow2.modify_hardware_config vm_name=<name> [cpu=<count>] [memory=<size>] [pci=<id>] [start=<bool>]
:param vm_name: Name of the virtual machine to modify.
:param cpu: Number of virtual CPUs to assign.
:param memory: Amount of memory to assign in MiB.
:param pci: PCI hardware ID to passthrough to the VM (e.g., '0000:00:1f.2').
:param start: Boolean flag to start the VM after modification.
Options:
vm_name
Name of the virtual machine to modify
cpu
Number of virtual CPUs to assign (positive integer)
Optional - VM's current CPU count retained if not specified
memory
Amount of memory to assign in MiB (positive integer)
Optional - VM's current memory size retained if not specified
pci
PCI hardware ID to passthrough to the VM (e.g., '0000:00:1f.2')
Optional - no PCI passthrough if not specified
start
Boolean flag to start the VM after modification
Optional - defaults to False
:return: A dictionary with the result of the script execution.
Examples:
1. **Modify CPU and Memory:**
```bash
salt '*' qcow2.modify_hardware_config vm_name='sensor1' cpu=4 memory=8192
```
This assigns 4 CPUs and 8GB memory to the VM
CLI Example:
2. **Enable PCI Passthrough:**
```bash
salt '*' qcow2.modify_hardware_config vm_name='sensor1' pci='0000:00:1f.2' start=True
```
This configures PCI passthrough and starts the VM
.. code-block:: bash
3. **Complete Hardware Configuration:**
```bash
salt '*' qcow2.modify_hardware_config vm_name='sensor1' cpu=8 memory=16384 pci='0000:00:1f.2' start=True
```
This sets CPU, memory, PCI passthrough, and starts the VM
salt '*' qcow2.modify_hardware_config vm_name='my_vm' cpu=4 memory=8192 pci='0000:00:1f.2' start=True
Notes:
- VM must be stopped before modification unless only the start flag is set
- Memory is specified in MiB (1024 = 1GB)
- PCI devices must be available and not in use by the host
- CPU count should align with host capabilities
- Requires so-kvm-modify-hardware script to be installed
Description:
This function modifies the hardware configuration of a KVM virtual machine using
the so-kvm-modify-hardware script. It can adjust CPU count, memory allocation,
and PCI device passthrough. Changes are applied to the VM's libvirt configuration.
The VM can optionally be started after modifications are complete.
Exit Codes:
0: Success
1: Invalid parameters
2: VM state error (running when should be stopped)
3: Hardware configuration error
4: System command error
255: Unexpected error
Logging:
- All operations are logged to the salt minion log
- Log entries are prefixed with 'qcow2 module:'
- Hardware configuration changes are logged
- Errors include detailed messages and stack traces
- Final status of modification is logged
'''
cmd = ['/usr/sbin/so-kvm-modify-hardware', '-v', vm_name]

102
salt/hypervisor/tools/sbin/so-kvm-modify-hardware
View File

@@ -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
"""

110
salt/hypervisor/tools/sbin/so-qcow2-modify-network
View File

@@ -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}")

183
salt/manager/tools/sbin/so-salt-cloud
View File

@@ -6,13 +6,39 @@
# Elastic License 2.0.
"""
Script to assist with salt-cloud VM provisioning. This is intended to work with a libvirt salt-cloud provider.
Script for automated virtual machine provisioning and configuration in Security Onion's virtualization infrastructure.
This script integrates multiple components to provide a streamlined VM deployment process:
**Usage:**
python so-salt-cloud -p <profile> <vm_name> (--dhcp4 | --static4 --ip4 <ip_address> --gw4 <gateway>)
1. Salt Cloud Integration:
- Works with libvirt salt-cloud provider for VM creation
- Manages VM lifecycle from provisioning through configuration
- Handles profile-based deployment for consistent VM setups
2. Network Configuration Management:
- Supports both DHCP and static IPv4 networking
- Pre-configures network settings before VM deployment
- Integrates with qcow2.modify_network_config for image modification
- Ensures VMs boot with correct network configuration
3. Hardware Resource Management:
- Flexible CPU and memory allocation
- Advanced PCI device passthrough capabilities
- Controlled VM startup sequence
- Uses qcow2.modify_hardware_config for hardware settings
4. Security Integration:
- Automatic firewall rule configuration
- Integrates with so-firewall-minion for firewall setup on the manager
This script serves as the primary interface for VM deployment in Security Onion, coordinating
between salt-cloud, network configuration, hardware management, and security components to
ensure proper VM provisioning and configuration.
Usage:
so-salt-cloud -p <profile> <vm_name> (--dhcp4 | --static4 --ip4 <ip_address> --gw4 <gateway>)
[-c <cpu_count>] [-m <memory_amount>] [-P <pci_id>] [-P <pci_id> ...] [--dns4 <dns_servers>] [--search4 <search_domain>]
**Options:**
Options:
-p, --profile The cloud profile to build the VM from.
<vm_name> The name of the VM.
--dhcp4 Configure interface for DHCP (IPv4).
@@ -25,98 +51,131 @@ Script to assist with salt-cloud VM provisioning. This is intended to work with
-m, --memory Amount of memory to assign in MiB.
-P, --pci PCI hardware ID(s) to passthrough to the VM (e.g., 0000:00:1f.2). Can be specified multiple times.
**Examples:**
Examples:
1. **Static IP Configuration with Multiple PCI Devices:**
1. Static IP Configuration with Multiple PCI Devices:
```bash
python so-salt-cloud -p core-hype1 vm1_sensor --static4 --ip4 192.168.1.10/24 --gw4 192.168.1.1 \
Command:
so-salt-cloud -p sool9-hyper1 vm1_sensor --static4 --ip4 192.168.1.10/24 --gw4 192.168.1.1 \
--dns4 192.168.1.1,192.168.1.2 --search4 example.local -c 4 -m 8192 -P 0000:00:1f.2 -P 0000:00:1f.3
```
This command provisions a VM named `vm1_sensor` using the `core-hype1` profile with the following settings:
This command provisions a VM named vm1_sensor using the sool9-hyper1 profile with the following settings:
- 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`
- 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
- Hardware Configuration:
- CPUs: `4`
- Memory: `8192` MiB
- PCI Device Passthrough: `0000:00:1f.2`, `0000:00:1f.3`
- CPUs: 4
- Memory: 8192 MiB
- PCI Device Passthrough: 0000:00:1f.2, 0000:00:1f.3
2. **DHCP Configuration with Default Hardware Settings:**
2. DHCP Configuration with Default Hardware Settings:
```bash
python so-salt-cloud -p core-hype1 vm2_master --dhcp4
```
Command:
so-salt-cloud -p sool9-hyper1 vm2_master --dhcp4
This command provisions a VM named `vm2_master` using the `core-hype1` profile with DHCP for network configuration and default hardware settings.
This command provisions a VM named vm2_master using the sool9-hyper1 profile with DHCP for network configuration and default hardware settings.
3. **Static IP Configuration without Hardware Specifications:**
3. Static IP Configuration without Hardware Specifications:
```bash
python so-salt-cloud -p core-hype1 vm3_search --static4 --ip4 192.168.1.20/24 --gw4 192.168.1.1
```
Command:
so-salt-cloud -p sool9-hyper1 vm3_search --static4 --ip4 192.168.1.20/24 --gw4 192.168.1.1
This command provisions a VM named `vm3_search` with a static IP configuration and default hardware settings.
This command provisions a VM named vm3_search with a static IP configuration and default hardware settings.
4. **DHCP Configuration with Custom Hardware Specifications and Multiple PCI Devices:**
4. DHCP Configuration with Custom Hardware Specifications and Multiple PCI Devices:
```bash
python so-salt-cloud -p core-hype1 vm4_node --dhcp4 -c 8 -m 16384 -P 0000:00:1f.4 -P 0000:00:1f.5
```
Command:
so-salt-cloud -p sool9-hyper1 vm4_node --dhcp4 -c 8 -m 16384 -P 0000:00:1f.4 -P 0000:00:1f.5
This command provisions a VM named `vm4_node` using DHCP for network configuration and custom hardware settings:
This command provisions a VM named vm4_node using DHCP for network configuration and custom hardware settings:
- CPUs: `8`
- Memory: `16384` MiB
- PCI Device Passthrough: `0000:00:1f.4`, `0000:00:1f.5`
- CPUs: 8
- Memory: 16384 MiB
- PCI Device Passthrough: 0000:00:1f.4, 0000:00:1f.5
**Notes:**
5. Static IP Configuration with DNS and Search Domain:
- When using `--static4`, both `--ip4` and `--gw4` options are required.
- The script assumes the cloud profile name follows the format `basedomain-hypervisorname`.
- Hardware parameters (`-c`, `-m`, `-P`) are optional. If not provided, default values from the profile will be used.
- The `-P` or `--pci` option can be specified multiple times to pass through multiple PCI devices to the VM.
- The `vm_name` should include the role of the VM after an underscore (e.g., `hostname_role`), as the script uses this to determine the VM's role for firewall configuration.
Command:
so-salt-cloud -p sool9-hyper1 vm1_sensor --static4 --ip4 192.168.1.10/24 --gw4 192.168.1.1 --dns4 192.168.1.1 --search4 example.local
**Description:**
This command provisions a VM named vm1_sensor using the sool9-hyper1 profile with static IPv4 configuration:
The `so-salt-cloud` script automates the provisioning of virtual machines using SaltStack's `salt-cloud` utility. It performs the following steps:
- Static IPv4 configuration:
- IP Address: 192.168.1.10/24
- Gateway: 192.168.1.1
- DNS Server: 192.168.1.1
- DNS Search Domain: example.local
1. **Network Configuration:**
Notes:
- Modifies the network settings of the base QCOW2 image before provisioning.
- Supports both DHCP and static IPv4 configurations.
- Uses the `qcow2.modify_network_config` module via SaltStack to apply these settings on the target hypervisor.
- When using --static4, both --ip4 and --gw4 options are required.
- The script assumes the cloud profile name follows the format basedomain-hypervisorname.
- Hardware parameters (-c, -m, -P) are optional. If not provided, default values from the profile will be used.
- The -P or --pci option can be specified multiple times to pass through multiple PCI devices to the VM.
- The vm_name should include the role of the VM after an underscore (e.g., hostname_role), as the script uses this to determine the VM's role for firewall configuration.
2. **VM Provisioning:**
Description:
- Calls `salt-cloud` to provision the VM using the specified profile and VM name.
- The VM is provisioned but not started immediately to allow for hardware configuration.
The so-salt-cloud script automates the provisioning and configuration of virtual machines in Security Onion's infrastructure. It orchestrates multiple components to ensure proper VM setup and security configuration. The script executes in the following phases:
3. **Hardware Configuration:**
1. Network Configuration Phase:
- Pre-deployment network setup using qcow2.modify_network_config
- Supports both DHCP and static IPv4 configurations
- Modifies the base QCOW2 image directly to ensure network settings persist
- Handles DNS and search domain configuration for proper name resolution
- Validates network parameters before modification
- Ensures network settings are in place before VM creation
- Modifies the hardware settings of the newly defined VM.
- Supports specifying multiple PCI devices for passthrough.
- Uses the `qcow2.modify_hardware_config` module via SaltStack to adjust CPU count, memory allocation, and PCI device passthrough.
- Starts the VM after hardware modifications.
2. VM Provisioning Phase:
- Leverages salt-cloud for consistent VM deployment
- Uses predefined profiles for standardized configurations
- Manages the VM lifecycle through libvirt
- Prevents automatic VM start to allow hardware configuration
- Validates profile and VM name format
- Extracts role information from VM name for security configuration
4. **Firewall Configuration:**
3. Hardware Configuration Phase:
- Configures VM hardware through qcow2.modify_hardware_config
- Manages CPU allocation based on host capabilities
- Handles memory assignment in MiB units
- Supports multiple PCI device passthrough for advanced networking
- Validates hardware parameters against host resources
- Controls VM startup sequence after configuration
- Monitors the output of `salt-cloud` to extract the VM's IP address.
- Calls the `so-firewall-minion` script to apply firewall rules based on the VM's role.
4. Security Integration Phase:
- Monitors salt-cloud output for VM IP address assignment
- Extracts role information from VM name
- Launches so-firewall-minion in a separate thread for non-blocking operation
- Configures role-based firewall rules automatically
- Ensures security policies are in place before VM is accessible
- Logs all security-related operations for audit purposes
**Exit Codes:**
The script implements extensive error handling and logging throughout each phase:
- Validates all input parameters before execution
- Provides detailed error messages for troubleshooting
- Logs operations to both file and console
- Handles process interruption gracefully
- Ensures atomic operations where possible
- Maintains audit trail of all configuration changes
- `0`: Success
Integration points:
- Works with Security Onion's salt-cloud provider
- Interfaces with qcow2 module for image and hardware management
- Coordinates with so-firewall-minion for security configuration
- Uses libvirt for VM management
- Leverages SaltStack for distributed execution
Exit Codes:
- 0: Success
- Non-zero: An error occurred during execution.
**Logging:**
Logging:
- Logs are written to `/opt/so/log/salt/so-salt-cloud.log`.
- Logs are written to /opt/so/log/salt/so-salt-cloud.log.
- Both file and console logging are enabled for real-time monitoring.
"""