# IP address management

Source: https://docs.quake.ai/docs/network/concepts/ip-addresses
Markdown: https://docs.quake.ai/docs/network/concepts/ip-addresses.md

---

# IP address management

Instances on Quake AI receive at least one private IP address from the subnet they connect to. How that address is allocated, how it reaches the guest OS, and what happens when you need multiple addresses or advanced forwarding are all governed by the Network service ([OpenStack Neutron](https://docs.openstack.org/neutron/latest/)).

## IP allocation methods

When you create a port or launch an instance, Quake AI assigns a private IP from the subnet's allocation pool in one of two ways:

**System-allocated (default):** The platform picks an unused address from the pool automatically. The assigned IP is guaranteed not to conflict with other active addresses on the subnet.

**Manually assigned:** You specify the IP address at port or instance creation time. The address can be inside or outside the subnet's allocation pool. The Console may show a warning for out-of-pool addresses, but the assignment succeeds as long as the address is not already in use.

Both methods produce the same result: a port with a fixed IP recorded in Neutron's database. The allocation method has no effect on how the address reaches the guest OS.

## DHCP vs. static configuration inside the instance

The allocation method in Quake AI is independent of how the guest OS configures the interface. Any combination works:

| Allocation method | DHCP in guest | Static in guest |
|---|---|---|
| System-allocated | DHCP delivers the assigned IP automatically | You can configure the same IP statically |
| Manually assigned | If DHCP is enabled on the subnet, the assigned IP is served via DHCP | Configure the IP manually or with automation |

When DHCP is enabled on the subnet (the default), the Neutron DHCP agent serves the assigned fixed IP to the instance. DHCP is the default guest configuration path on most subnets.

When DHCP is disabled, or when you prefer static configuration, the guest must be configured to match the IP recorded in the port metadata. Mismatches between the guest IP and the port IP cause traffic to be dropped by port security.

## Allowed address pairs

By default, a port only permits traffic from its assigned fixed IP and MAC address. Any packet with a different source address is dropped by the virtual switch. This is **port security**, designed to prevent IP spoofing.

**Allowed address pairs** let you explicitly authorize additional IP/MAC combinations on a port. This is necessary for:

- **Virtual IPs for high availability** (Keepalived, Pacemaker)
- **Software load balancers** (HAProxy active-standby)
- **NAT gateways** forwarding traffic for other instances
- **Multi-IP interfaces** for applications that bind to multiple addresses

### Adding allowed address pairs

```bash
openstack port set --allowed-address ip-address=192.168.1.100 YOUR_PORT_ID
```

To specify a different MAC address:

```bash
openstack port set \
  --allowed-address ip-address=192.168.1.100,mac-address=fa:16:3e:12:34:56 \
  YOUR_PORT_ID
```

Verify the current allowed address pairs:

```bash
openstack port show YOUR_PORT_ID -f json | jq '.allowed_address_pairs'
```



Allowed address pairs can only be used on internal project networks. They are not permitted on public or external networks for security reasons.



Security groups still apply to traffic from allowed addresses. The MAC address defaults to the port's MAC if not specified. Avoid wildcard entries (`0.0.0.0/0`); they can cause IP conflicts and bypass intended routing controls.

## Disabling port security

Port security enforces source IP/MAC validation and security group filtering on every port. Disabling it removes both protections, allowing the instance to:

- Forward packets from arbitrary source IPs (NAT, routing)
- Receive traffic without security group filtering
- Act as a router, bridge, or Layer 2/Layer 3 appliance

### When to disable port security

- Virtual routers using `iptables` or `nftables`
- NAT gateways forwarding traffic for a private subnet
- Software load balancers handling forwarded traffic
- Custom network appliances (firewalls, VPNs)

### Disabling on a new port

```bash
openstack port create \
  --network YOUR_NETWORK \
  --no-security-group \
  --disable-port-security \
  YOUR_PORT_NAME
```

### Disabling on an existing port

```bash
openstack port set \
  --no-security-group \
  --disable-port-security \
  YOUR_PORT_ID
```



Disabling port security removes IP spoofing protection and security group enforcement. Only disable it on internal project networks where the instance's behavior is well understood and external controls (ACLs, router filters) are in place.



## Key points

- Quake AI tracks IP-to-port mappings regardless of whether the guest uses DHCP or static configuration.
- Manually assigned IPs still pass through network security and routing controls.
- Allowed address pairs and disabled port security suit HA, NAT, and appliance workloads; keep port security enabled for standard instance NICs.
- Address conflicts are your responsibility when using allowed address pairs or disabled port security.

## Further reading

- [Floating IPs](/docs/network/concepts/floating-ips): public IP addresses for external access
- [Security groups](/docs/network/concepts/security-groups): firewall rules for ports and instances
- [Create a security group](/docs/network/how-to/create-security-group): configure inbound and outbound rules
- [Allocate floating IPs](/docs/network/how-to/allocate-floating-ips): assign public IPs to instances
- [Instance connectivity troubleshooting](/docs/operate/runbooks/instance-connectivity): diagnose port security and networking issues