pfSense ALTQ Traffic Shaper - Wizards and QoS Setup

ALTQ (Alternate Queuing) is a queuing framework built into the pf (packet filter) subsystem of FreeBSD. In pfSense, ALTQ provides traffic prioritization, guaranteed bandwidth for critical applications, and hierarchical bandwidth distribution. ALTQ operates through a queue system: traffic is classified by firewall rules and directed into corresponding queues, each with its own priority and bandwidth parameters.

The fundamental difference between ALTQ and Limiters is bandwidth borrowing. When a VoIP queue is not consuming its allocated 2 Mbit/s, that bandwidth is automatically redistributed to other queues. Limiters do not support this behavior - unused bandwidth in a dummynet pipe is simply wasted.

Warning:

ALTQ is tightly coupled to network interface card drivers. Not all drivers support ALTQ - verify NIC compatibility before configuring the shaper. Enabling ALTQ reduces the maximum throughput capacity of the firewall, as queue processing adds CPU overhead.

Scheduler Types

pfSense supports four ALTQ scheduler types. The scheduler determines the algorithm used to distribute bandwidth among queues.

PRIQ (Priority Queuing)

The simplest scheduler type. All queues reside at a single level directly under the root queue - hierarchical nesting is not supported. Each queue is assigned a priority from 0 to 15, where 15 is the highest. Higher-priority queues are serviced first.

Strengths: straightforward configuration and operation, minimal processing overhead.

Weaknesses: strict priority without a fairness mechanism. High-priority queues can completely starve lower-priority traffic. PRIQ does not account for bandwidth allocation - distribution is based solely on priority ordering.

Use case: scenarios requiring unconditional prioritization of one traffic type over another, where the link has sufficient capacity to prevent low-priority queue starvation.

CBQ (Class-Based Queuing)

Supports hierarchical queue structures with bandwidth borrowing from the parent queue. Priorities range from 0 to 7. Queues with equal priority are serviced using round-robin scheduling.

The sum of child queue bandwidth allocations must not exceed the parent queue bandwidth. Child queues can borrow unused bandwidth from their parent queue, but not from sibling queues.

Strengths: hierarchy support, bandwidth borrowing, predictable behavior.

Weaknesses: does not guarantee minimum bandwidth in absolute terms - only proportional distribution with borrowing.

Use case: scenarios requiring bandwidth distribution across traffic classes with dynamic redistribution of unused resources.

HFSC (Hierarchical Fair Service Curve)

The most capable scheduler. It supports hierarchical queue structures and provides minimum bandwidth guarantees through service curves. HFSC operates with three types of service curves:

Upper Limit - a hard bandwidth ceiling. Queue traffic cannot exceed this value. The m1 parameter limits burst capacity, d defines burst duration in milliseconds, and m2 defines the steady-state ceiling.

Real Time - guaranteed minimum bandwidth for child queues. The m2 value in the real-time curve must not exceed 30% of the parent queue bandwidth. This mechanism ensures minimum guaranteed bandwidth for critical traffic.

Link Share - bandwidth distribution after real-time guarantees are fulfilled. This determines how unused bandwidth is distributed among queues.

Strengths: guaranteed bandwidth, flexible burst control, the most complete resource management.

Weaknesses: configuration complexity, requirement for precise service curve calculations.

Use case: VoIP, video conferencing, environments with strict QoS requirements where absolute bandwidth guarantees are necessary.

FAIRQ (Fair Queuing)

Processes queues from highest to lowest priority while striving for fair bandwidth distribution among all connections. Packets from underfilled lower-priority queues are processed before packets from overfilled higher-priority queues.

Connections may briefly exceed the queue bandwidth, but average consumption is maintained at the defined queue bandwidth level.

Strengths: fair distribution prevents starvation of low-priority traffic.

Weaknesses: not supported by the wizard - requires manual configuration only.

Use case: scenarios where fair distribution is more important than strict prioritization.

Scheduler Comparison

Wizard-Based Configuration

The Traffic Shaper Wizard is the recommended approach for initial ALTQ setup. The wizard generates a set of queues and floating rules covering common prioritization scenarios.

Accessing the Wizard

Navigate to Firewall > Traffic Shaper > Wizards. pfSense offers several wizard variants:

• Traffic Shaper Wizard - the primary wizard for traffic prioritization setup
• Multiple LAN/WAN - a wizard for configurations with multiple WAN or LAN interfaces

Wizard Steps

Step 1: Interface Selection

Specify the WAN interface (or multiple, in a multi-WAN configuration) and the LAN interface. The wizard creates a separate queue set for each WAN interface.

Step 2: Link Speeds

Enter the upload and download speeds for the WAN connection. Setting these to 85-95% of the actual link speed is recommended. Specifying full link speed causes buffering in ISP equipment, which negates the prioritization effect.

Select the scheduler type. HFSC (provides bandwidth guarantees) or PRIQ (simple prioritization without guarantees) is recommended for most scenarios.

Step 3: VoIP

Configure VoIP traffic prioritization. The wizard offers a predefined list of VoIP providers or manual parameter entry. When enabled, VoIP traffic receives the highest priority.

Available parameters:

• Enable - activate VoIP prioritization
• Provider - selection from known VoIP providers (determines ports and protocols)
• Connection Upload/Download - bandwidth allocated to VoIP

Step 4: Penalty Box

The Penalty Box forcibly restricts specific IP addresses or subnets by placing them in the lowest-priority queue. Traffic from Penalty Box hosts is serviced only when spare bandwidth is available.

• Enable - activate Penalty Box
• Address - IP addresses or subnets to penalize
• Bandwidth - maximum bandwidth for the Penalty Box (as a percentage of total or in absolute values)

Step 5: P2P Networking

Configure throttling for P2P traffic (BitTorrent and similar protocols). P2P traffic is placed in a low-priority queue.

• Enable - activate P2P throttling
• Bandwidth - bandwidth allocation for P2P traffic

Warning:

P2P traffic detection relies on known ports and protocols. Encrypted P2P traffic on non-standard ports may not be identified correctly and will be treated as regular traffic.

Step 6: Traffic Categories

The wizard provides priority settings for standard categories:

• Games - online gaming traffic (high priority)
• Other networking protocols - ICMP, DNS, SNMP (medium-high priority)
• Multimedia/Streaming - audio and video streaming
• Work/Business - HTTPS, IMAP, SMTP, SSH (medium-high priority)

For each category, the following can be configured:

• Enable/disable prioritization
• Bandwidth allocation (when using HFSC or CBQ)

Step 7: Apply

The wizard generates queues and floating rules and applies the configuration. All existing shaper queues and rules are deleted and replaced.

Warning:

Re-running the wizard completely overwrites the current shaper configuration. All manual queue and rule modifications will be lost. Before running the wizard, create a configuration backup at Diagnostics > Backup & Restore.

Manual Queue Configuration

After creating a baseline configuration with the wizard - or when fine-grained control is required - queues can be created and edited manually.

Creating the Root Queue

1. Navigate to Firewall > Traffic Shaper > By Interface
2. Select the interface (WAN or LAN)
3. Configure the root queue:
   • Scheduler Type - scheduler algorithm (PRIQ, CBQ, HFSC, or FAIRQ)
   • Bandwidth - total interface bandwidth
   • Queue Limit - maximum packets in the queue
4. Save

Creating Child Queues

1. Select the root queue in the interface tree
2. Click Add new Queue
3. Configure parameters:
   • Queue Name - queue name (no spaces)
   • Priority - priority level (depends on scheduler type)
   • Bandwidth - bandwidth for CBQ/HFSC
   • Bandwidth Type - units (%, Kbit/s, Mbit/s)
   • Queue Limit - queue depth in packets
   • Default Queue - mark one queue as default (for unclassified traffic)
4. Save

HFSC Service Curve Parameters

When using HFSC, three service curves are available for each child queue:

Upper Limit Service Curve:

• m1 - burst bandwidth (Kbit/s)
• d - burst duration (ms)
• m2 - steady-state bandwidth cap (Kbit/s)

Real Time Service Curve:

• m1 - initial burst guarantee
• d - burst duration
• m2 - minimum guaranteed bandwidth (must not exceed 30% of parent queue)

Link Share Service Curve:

• m1 - burst sharing bandwidth
• d - burst duration
• m2 - steady-state share

For typical scenarios, setting only the m2 parameter in each curve while leaving m1 and d at zero is sufficient.

Assigning Traffic to Queues

Traffic is directed into queues through firewall rules. Two methods are available:

Floating rules with Match action:

1. Navigate to Firewall > Rules > Floating
2. Create a rule with action Match (not Pass or Block)
3. Specify traffic classification parameters (ports, protocols, addresses)
4. In the rule settings, select Ack Queue and Queue
5. A Match rule does not affect whether traffic is passed or blocked - it only classifies packets and directs them to the appropriate queues

Interface rules with Pass action:

1. In an existing Pass rule on the interface tab
2. Under Advanced, select Ack Queue and Queue
3. Packets matching this rule will be directed to the specified queue

Ack Queue is used to separate TCP ACK packets into a dedicated queue. This is recommended practice, as ACK delay significantly degrades TCP throughput.

DiffServ and DSCP Marking

ALTQ supports marking packets with DSCP (Differentiated Services Code Point) values. Marking is useful when coordinating with an ISP or upstream router that supports DiffServ.

Standard DSCP Values

Configuring DSCP Marking

Marking is configured in the queue parameters. Packets entering the queue are marked with the specified DSCP value upon egress from the interface.

Inbound DSCP marks from the ISP can be used for classification - pfSense can read DSCP tags on incoming packets and direct them to appropriate queues based on firewall rules filtered by DSCP values.

Hardware Limitations

NIC Driver Compatibility

ALTQ operates only with network adapters whose drivers support the ALTQ framework. Commonly compatible drivers include:

When an incompatible driver is in use, ALTQ does not activate and queues are not created. The error is logged to the system journal. In this case, use Limiters instead, as they are driver-independent.

To verify compatibility for a specific adapter, check System > General Setup to identify the interface driver name, then verify its presence in the compatible driver list in the Netgate documentation.

Performance Impact

Enabling ALTQ reduces the maximum firewall throughput. On hardware with ARM or Atom processors, the reduction can reach 30-50%. Server-grade hardware with Xeon processors is less affected, but the impact is still measurable.

Recommendations:

• On links exceeding 1 Gbit/s, evaluate whether the hardware delivers adequate throughput with ALTQ active
• On links exceeding 10 Gbit/s, ALTQ is generally impractical - use Limiters or dedicated QoS hardware instead
• Perform throughput testing after enabling the shaper

Queue Monitoring

Status > Queues

The Status > Queues page displays the state of all active queues in real time:

• Queue name and position in the hierarchy
• Current utilization (as a percentage of allocated bandwidth)
• Number of packets in the queue
• Dropped packet counter (drops)
• Utilization graphs

A high drop count indicates insufficient bandwidth for the queue. If drops are growing in critical queues (VoIP, interactive traffic), the bandwidth allocation needs to be revised.

Interpreting Graphs

For the shaper to function correctly, the root queue graph should show utilization close to 100% during peak load periods. If the root queue utilization remains below 50% during load periods, the total bandwidth value is set too high and the shaper is not performing its function.

Troubleshooting

Wizard Does Not Apply Configuration

1. Verify that the NIC driver is ALTQ-compatible. Check System > General Setup to identify the driver.
2. Review the system log (Status > System Logs) for ALTQ-related errors.
3. Confirm that the upload/download speeds specified are correct and do not exceed the physical link capacity.

Queues Created but Traffic Not Being Prioritized

1. Verify that floating rules with Match action are created and active (Firewall > Rules > Floating).
2. Confirm that traffic matches the classification rules - check Diagnostics > States.
3. Review Status > Queues - if traffic is not reaching the target queues, the classification rules are incorrect.
4. Ensure one queue is designated as Default - unclassified traffic is routed there.

High Drop Counts in Queues

1. Drops are expected behavior for low-priority queues under heavy load.
2. Drops in high-priority queues indicate insufficient allocated bandwidth.
3. Increase the bandwidth allocation for the affected queue or revise the distribution.
4. Verify that the total link speed is configured correctly (85-95% of actual speed).

Incompatible NIC Driver

If the network adapter does not support ALTQ:

1. Use Limiters instead of ALTQ - they are driver-independent
2. If prioritization is required, consider replacing the NIC with a compatible model (Intel igb, em, or ix)
3. In virtual environments, ensure the vtnet (KVM/QEMU) or vmx (VMware) driver is in use

Related Sections

• pfSense Traffic Shaper - bandwidth management overview, ALTQ vs Limiters comparison
• Limiters - per-IP and per-subnet bandwidth limiting through dummynet
• Firewall Rules - creating rules and floating rules for traffic classification