HotsTac(k)os Configuration Guide

This guide covers all configuration options available in HotsTac(k)os. Most defaults work well for development environments, but you can customize settings to match your specific needs.

Configuration File

All configuration is managed through the .env file in the devsetup/hotstack-os/ directory:

Copy the example configuration:
```
cp .env.example .env
```
Edit .env to customize settings (optional - defaults work for most users)

Re-install to apply changes:

sudo make install

Then restart services:

sudo systemctl restart hotstack-os.target

Messaging Backend

HotsTac(k)os uses RabbitMQ for oslo.messaging (RPC and notifications).

RabbitMQ credentials can be configured in .env:

RABBITMQ_DEFAULT_USER=openstack
RABBITMQ_DEFAULT_PASS=openstack

Authentication & Passwords

Security Warning: Default passwords are simple and intended for development only. Change these for any environment exposed to networks.

Setting	Default	Description
`KEYSTONE_ADMIN_PASSWORD`	`admin`	Admin user password for Keystone
`MYSQL_ROOT_PASSWORD`	`rootpass`	MariaDB root password
`DB_PASSWORD`	`openstack`	Database password for OpenStack services
`SERVICE_PASSWORD`	`openstack`	Password for inter-service API authentication
`RABBITMQ_DEFAULT_USER`	`openstack`	RabbitMQ username
`RABBITMQ_DEFAULT_PASS`	`openstack`	RabbitMQ password

Example .env customization:

KEYSTONE_ADMIN_PASSWORD=MySecurePassword123
DB_PASSWORD=DatabasePass456
SERVICE_PASSWORD=ServicePass789

OpenStack Release

Control which OpenStack release to use:

Setting	Default	Description
`OPENSTACK_BRANCH`	`stable/2025.2`	OpenStack release branch

Available options:

stable/2025.2 - Flamingo (latest stable, recommended)
master - Development branch (not recommended for stability)

Example:

OPENSTACK_BRANCH=stable/2025.2

Logging Configuration

Control verbosity of OpenStack service logs:

Setting	Default	Description
`DEBUG_LOGGING`	`false`	Enable DEBUG level logging for all services

When false: Only INFO, WARNING, and ERROR messages are logged When true: Verbose DEBUG messages are included (useful for troubleshooting)

Example:

DEBUG_LOGGING=true

Network Configuration

Address Space

HotsTac(k)os uses a dedicated 172.31.0.0/24 address space split into two subnets:

Setting	Default	Description
`CONTAINER_NETWORK`	`172.31.0.0/25`	Podman bridge for service containers (.0-.127)
`PROVIDER_NETWORK`	`172.31.0.128/25`	OVS hot-ex bridge for VM connectivity (.128-.255)
`BREX_IP`	`172.31.0.129`	IP address for hot-ex bridge (host connectivity)

Important: Only change these if the default range conflicts with existing networks on your machine.

Service IP Addresses

All OpenStack service containers use static IPs within the CONTAINER_NETWORK range:

Infrastructure Services

MARIADB_IP=172.31.0.3
RABBITMQ_IP=172.31.0.4
MEMCACHED_IP=172.31.0.5
HAPROXY_IP=172.31.0.6

Identity & Core Services

KEYSTONE_IP=172.31.0.11
GLANCE_IP=172.31.0.12
PLACEMENT_IP=172.31.0.13

Compute Services (Nova)

NOVA_API_IP=172.31.0.21
NOVA_CONDUCTOR_IP=172.31.0.22
NOVA_SCHEDULER_IP=172.31.0.23
NOVA_COMPUTE_IP=172.31.0.24
NOVA_METADATA_IP=172.31.0.25
NOVA_NOVNCPROXY_IP=172.31.0.26

Networking Services (OVN/Neutron)

OVN_NORTHD_IP=172.31.0.31
NEUTRON_SERVER_IP=172.31.0.32

Block Storage Services (Cinder)

CINDER_API_IP=172.31.0.41
CINDER_SCHEDULER_IP=172.31.0.42
CINDER_VOLUME_IP=172.31.0.43

Orchestration Services (Heat)

HEAT_API_IP=172.31.0.51
HEAT_ENGINE_IP=172.31.0.53

Region Name

Setting	Default	Description
`REGION_NAME`	`RegionOne`	OpenStack region name (affects service catalog)

MTU Configuration

Setting	Default	Description
`GLOBAL_PHYSNET_MTU`	`9216`	MTU of the underlying physical network (maximum jumbo frame size)
`PATH_MTU`	`9216`	MTU for overlay/tunnel networks (should match GLOBAL_PHYSNET_MTU)

Jumbo Frames Support:

HotStack-OS is configured with jumbo frames by default (9216 MTU) for optimal tenant networking. Neutron automatically calculates the appropriate MTU for tenant networks by subtracting overlay protocol overhead:

GENEVE overlay: 38 bytes overhead
- Physical MTU: 9216 (default)
- Tenant network MTU: 9178 (9216 - 38)
- VM interfaces: 9178 MTU
- Result: VMs can run 9000 MTU workloads

Common MTU Values:

9216: Maximum jumbo frames (yields ~9178 MTU for VMs) - default
9000: Common jumbo frames (yields ~8962 MTU for VMs)
1500: Standard Ethernet (yields ~1462 MTU for VMs)

Configuration Example:

# In .env file - default is already 9216
GLOBAL_PHYSNET_MTU=9216
PATH_MTU=9216

# Or reduce to standard Ethernet if needed
# GLOBAL_PHYSNET_MTU=1500
# PATH_MTU=1500

Storage Configuration

Data Directory

Setting	Default	Description
`HOTSTACK_DATA_DIR`	`/var/lib/hotstack-os`	Root directory for all persistent data

This directory contains:

MariaDB databases
Glance images
Service logs
RabbitMQ data

The make install command creates this directory structure automatically.

Custom location example:

HOTSTACK_DATA_DIR=/home/myuser/hotstack-data

Nova Instances Path

Setting	Default	Description
`NOVA_INSTANCES_PATH`	`${HOTSTACK_DATA_DIR}/nova-instances`	Directory for VM instance files on host

This directory is used for VM disk images and instance state:

Maps directly to Nova's instances_path configuration option
Created automatically by make install with hotstack:kvm ownership
Bind-mounted into the nova-compute container with shared propagation
CRITICAL: Must use identical path in both host and container for libvirt compatibility
Requires libvirt access and proper SELinux context
Defaults to isolated path under HOTSTACK_DATA_DIR to avoid conflicts with system Nova

For custom paths, set SELinux context:

sudo semanage fcontext -a -t svirt_image_t "/custom/path(/.*)?"
sudo restorecon -Rv /custom/path

Nova Volume Mounts

Setting	Default	Description
`NOVA_NFS_MOUNT_POINT_BASE`	`${HOTSTACK_DATA_DIR}/nova-mnt`	Directory for volume mounts on host

This directory is used by Nova to mount Cinder volumes when attaching them to instances:

Maps directly to Nova's libvirt.nfs_mount_point_base configuration option
mount.nfs wrapper creates bind mounts here for direct filesystem access
Created automatically by make install
Bind-mounted into the nova-compute container with shared propagation
CRITICAL: Must use identical path in both host and container for libvirt compatibility
Accessible to libvirt on the host for VM disk access
Defaults to isolated path under HOTSTACK_DATA_DIR to avoid conflicts with system Nova

For custom paths, set SELinux context:

sudo semanage fcontext -a -t virt_var_lib_t "/custom/path(/.*)?"
sudo restorecon -Rv /custom/path

Cinder NFS Storage

Setting	Default	Description
`CINDER_NFS_EXPORT_DIR`	`/var/lib/hotstack-os/cinder-nfs`	Storage directory for Cinder volumes

This directory is:

Used by mount.nfs wrapper for direct filesystem access via bind mounts
Accessed by cinder-volume container for volume management
Accessed by nova-compute container for attaching volumes to VMs

The make install command creates this directory automatically.

HotStack Project Quotas

Quotas for the hotstack project created by make post-setup. Defaults are generous for development.

Compute Quotas

HOTSTACK_QUOTA_COMPUTE_CORES=40
HOTSTACK_QUOTA_COMPUTE_RAM=102400           # 100GB in MB
HOTSTACK_QUOTA_COMPUTE_INSTANCES=20
HOTSTACK_QUOTA_COMPUTE_KEY_PAIRS=10
HOTSTACK_QUOTA_COMPUTE_SERVER_GROUPS=10
HOTSTACK_QUOTA_COMPUTE_SERVER_GROUP_MEMBERS=10

Network Quotas

HOTSTACK_QUOTA_NETWORK_NETWORKS=20
HOTSTACK_QUOTA_NETWORK_SUBNETS=20
HOTSTACK_QUOTA_NETWORK_PORTS=100
HOTSTACK_QUOTA_NETWORK_ROUTERS=10
HOTSTACK_QUOTA_NETWORK_FLOATINGIPS=20
HOTSTACK_QUOTA_NETWORK_SECURITY_GROUPS=20
HOTSTACK_QUOTA_NETWORK_SECURITY_GROUP_RULES=100

Volume Quotas

HOTSTACK_QUOTA_VOLUME_VOLUMES=20
HOTSTACK_QUOTA_VOLUME_SNAPSHOTS=20
HOTSTACK_QUOTA_VOLUME_GIGABYTES=1000        # 1TB
HOTSTACK_QUOTA_VOLUME_PER_VOLUME_GIGABYTES=500

Post-Setup Network Configuration

Network settings used by make post-setup when creating default networks:

Setting	Default	Description
`HOTSTACK_PRIVATE_CIDR`	`192.168.100.0/24`	Private network CIDR for tenant VMs
`HOTSTACK_PROVIDER_CIDR`	`172.31.0.128/25`	Provider network CIDR (matches PROVIDER_NETWORK)
`HOTSTACK_PROVIDER_GATEWAY`	`172.31.0.129`	Provider network gateway (matches BREX_IP)

Post-Setup Image URLs

Image URLs used by make post-setup to download and upload images to Glance:

HOTSTACK_CIRROS_URL=http://download.cirros-cloud.net/0.6.2/cirros-0.6.2-x86_64-disk.img
HOTSTACK_CENTOS_STREAM_9_URL=https://cloud.centos.org/centos/9-stream/x86_64/images/CentOS-Stream-GenericCloud-x86_64-9-latest.x86_64.qcow2
HOTSTACK_CONTROLLER_IMAGE_URL=https://github.com/openstack-k8s-operators/hotstack/releases/download/latest-controller/controller-latest.qcow2
HOTSTACK_BLANK_IMAGE_URL=https://github.com/openstack-k8s-operators/hotstack/releases/download/latest-blank/blank-image-latest.qcow2
HOTSTACK_IPXE_BIOS_URL=https://github.com/openstack-k8s-operators/hotstack/releases/download/latest-ipxe/ipxe-bios-latest.img
HOTSTACK_IPXE_EFI_URL=https://github.com/openstack-k8s-operators/hotstack/releases/download/latest-ipxe/ipxe-efi-latest.img
HOTSTACK_NAT64_IMAGE_URL=https://github.com/openstack-k8s-operators/openstack-k8s-operators-ci/releases/download/latest/nat64-appliance-latest.qcow2

Notes:

Override to use custom HTTP/HTTPS mirrors
Local file paths are not supported (must be URLs)
Downloaded images are cached in ~/.cache/hotstack-os/images/

Advanced Configuration

OVN Chassis Hostname

Setting	Default	Description
`CHASSIS_HOSTNAME`	(auto-detected)	OVN chassis hostname for Neutron agent registration

Important: This must match the hostname Nova compute reports for port binding to work.

By default, auto-detected using hostname -f (FQDN) with fallback to hostname (short name). This matches Nova's hostname detection logic.

Override if:

System has no static hostname (only DHCP transient hostname)
You see "Refusing to bind port due to no OVN chassis" errors
Hostname changes between reboots or network changes

# Set to a stable hostname
CHASSIS_HOSTNAME=my-custom-hostname.example.com

Recommended: Set a static hostname on your system instead:

sudo hostnamectl set-hostname your-hostname.example.com

Configuration Changes

After modifying .env:

For most changes (passwords, IPs, network settings):

sudo make install              # Re-generate configs with new values
sudo systemctl restart hotstack-os.target

For OpenStack branch changes:

sudo make build                # Rebuild images with new branch
sudo make install              # Re-install with new configs
sudo systemctl restart hotstack-os.target
make post-setup                # Recreate resources if needed

For quota changes only:

make post-setup                # Quotas are applied during post-setup

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

HotsTac(k)os Configuration Guide

Configuration File

Messaging Backend

Authentication & Passwords

OpenStack Release

Logging Configuration

Network Configuration

Address Space

Service IP Addresses

Infrastructure Services

Identity & Core Services

Compute Services (Nova)

Networking Services (OVN/Neutron)

Block Storage Services (Cinder)

Orchestration Services (Heat)

Region Name

MTU Configuration

Storage Configuration

Data Directory

Nova Instances Path

Nova Volume Mounts

Cinder NFS Storage

HotStack Project Quotas

Compute Quotas

Network Quotas

Volume Quotas

Post-Setup Network Configuration

Post-Setup Image URLs

Advanced Configuration

OVN Chassis Hostname

Configuration Changes

See Also

FilesExpand file tree

CONFIGURATION.md

Latest commit

History

CONFIGURATION.md

File metadata and controls

HotsTac(k)os Configuration Guide

Configuration File

Messaging Backend

Authentication & Passwords

OpenStack Release

Logging Configuration

Network Configuration

Address Space

Service IP Addresses

Infrastructure Services

Identity & Core Services

Compute Services (Nova)

Networking Services (OVN/Neutron)

Block Storage Services (Cinder)

Orchestration Services (Heat)

Region Name

MTU Configuration

Storage Configuration

Data Directory

Nova Instances Path

Nova Volume Mounts

Cinder NFS Storage

HotStack Project Quotas

Compute Quotas

Network Quotas

Volume Quotas

Post-Setup Network Configuration

Post-Setup Image URLs

Advanced Configuration

OVN Chassis Hostname

Configuration Changes

See Also