Configuration

This guide describes all configuration parameters for VibeMQ.

Server Configuration 

BrokerOptions 

Main server configuration class:

public sealed class BrokerOptions {
    public int Port { get; set; } = 2925;
    public int MaxConnections { get; set; } = 1000;
    public int MaxMessageSize { get; set; } = 1_048_576;
    public AuthorizationOptions? Authorization { get; set; }
    public QueueDefaults QueueDefaults { get; set; } = new();
    public TlsOptions Tls { get; set; } = new();
    public RateLimitOptions RateLimit { get; set; } = new();
    public IReadOnlyList<CompressionAlgorithm> SupportedCompressions { get; set; }
        = [CompressionAlgorithm.Brotli, CompressionAlgorithm.GZip];
    public int CompressionThreshold { get; set; } = 1024;  // 1 KB
}

Authorization (default: null) enables username/password authentication with per-queue ACL. See Authorization for full details.

Persistence is configured on the builder, not in BrokerOptions: use BrokerBuilder.UseSqliteStorage(...) or BrokerBuilder.UseRedisStorage(...). See Persistence & Storage for details.

SupportedCompressions (default: Brotli, GZip) and CompressionThreshold (default: 1024 bytes) control frame-level compression. Use ConfigureFrom(BrokerOptions) to set them; see Communication Protocol for negotiation and framing.

Basic Parameters 

Port

Type: int

Default: 2925

TCP port for client connections:

.UsePort(2925)

Note

Make sure the port is not occupied by other applications.

MaxConnections

Type: int

Default: 1000

Maximum number of simultaneous connections:

.UseMaxConnections(5000)

Note

Increase for high-load scenarios.

MaxMessageSize

Type: int

Default: 1_048_576 (1 MB)

Maximum message size in bytes:

.UseMaxMessageSize(2_097_152)  // 2 MB

Warning

Large messages increase memory usage.

Authentication Activation

Authentication is automatically enabled when Authorization is configured:

options.Authorization = new AuthorizationOptions {
    SuperuserUsername = "admin",
    SuperuserPassword = "change-me"
};

Authorization

Type: AuthorizationOptions?

Default: null

Enables username/password authentication with per-queue ACL stored in SQLite. When set, legacy username/password authentication is automatically disabled.

.UseAuthorization(o => {
    o.SuperuserUsername = "admin";
    o.SuperuserPassword = Environment.GetEnvironmentVariable("VIBEMQ_ADMIN_PASS");
    o.DatabasePath = "/var/lib/vibemq/auth.db";
})

See Authorization for full details on users, ACL, and admin commands.

AuthorizationOptions

public sealed class AuthorizationOptions {
    public string SuperuserUsername { get; set; } = "vibemq";
    public string SuperuserPassword { get; set; } = "";
    public string DatabasePath { get; set; } = "auth.db";
}

Property	Default	Description
`SuperuserUsername`	`"vibemq"`	Username for the built-in superuser account.
`SuperuserPassword`	`""`	Password for the superuser. Must be set before the first run.
`DatabasePath`	`"auth.db"`	Path to the dedicated SQLite ACL database.

QueueDefaults 

Server-side default settings for auto-created queues (used by ConfigureQueues). Only these three properties are configurable as defaults; per-queue options (MessageTtl, DeadLetterQueue, OverflowStrategy, MaxRetryAttempts) are set via QueueOptions when creating a queue explicitly with CreateQueueAsync on the client or when the queue is created with custom options.

public sealed class QueueDefaults {
    public DeliveryMode DefaultDeliveryMode { get; set; } = DeliveryMode.RoundRobin;
    public int MaxQueueSize { get; set; } = 10_000;
    public bool EnableAutoCreate { get; set; } = true;
}

DefaultDeliveryMode

Type: DeliveryMode

Default: RoundRobin

Default delivery mode:

options.DefaultDeliveryMode = DeliveryMode.RoundRobin;

Possible values:

RoundRobin — round-robin delivery to one subscriber
FanOutWithAck — to all with acknowledgment
FanOutWithoutAck — to all without acknowledgment
PriorityBased — by priority

MaxQueueSize

Type: int

Default: 10_000

Maximum number of messages in queue:

options.MaxQueueSize = 100_000;

EnableAutoCreate

Type: bool

Default: true

Automatically create queues on first publish:

options.EnableAutoCreate = true;

Note

Disable for strict queue control. Per-queue options (MessageTtl, EnableDeadLetterQueue, OverflowStrategy, MaxRetryAttempts) are available in QueueOptions when creating a queue via client.CreateQueueAsync(name, options).

TlsOptions 

TLS/SSL settings:

public sealed class TlsOptions {
    public bool Enabled { get; set; }
    public string? CertificatePath { get; set; }
    public string? CertificatePassword { get; set; }
    public SslProtocols SslProtocols { get; set; } = SslProtocols.Tls12 | SslProtocols.Tls13;
    public bool RequireClientCertificate { get; set; }
}

Enabled

Type: bool

Default: false

Enable TLS:

.UseTls(options => {
    options.Enabled = true;
    options.CertificatePath = "/path/to/cert.pfx";
    options.CertificatePassword = "cert-password";
})

CertificatePath

Type: string?

Default: null

Path to PFX certificate:

options.CertificatePath = "/etc/ssl/vibemq.pfx";

CertificatePassword

Type: string?

Default: null

Certificate password:

options.CertificatePassword = "secure-password";

RateLimitOptions 

Rate limiting settings:

public sealed class RateLimitOptions {
    public bool Enabled { get; set; } = true;
    public int MaxConnectionsPerIpPerWindow { get; set; } = 20;
    public TimeSpan ConnectionWindow { get; set; } = TimeSpan.FromSeconds(60);
    public int MaxMessagesPerClientPerSecond { get; set; } = 1000;
}

Enabled

Type: bool

Default: true

Enable rate limiting:

.ConfigureRateLimiting(options => {
    options.Enabled = true;
})

MaxConnectionsPerIpPerWindow

Type: int

Default: 20

Maximum number of connections from one IP per time window:

options.MaxConnectionsPerIpPerWindow = 50;

ConnectionWindow

Type: TimeSpan

Default: 60 seconds

Time window for connection limiting:

options.ConnectionWindow = TimeSpan.FromSeconds(120);

MaxMessagesPerClientPerSecond

Type: int

Default: 1000

Maximum number of messages from client per second:

options.MaxMessagesPerClientPerSecond = 500;

Client Configuration 

ClientOptions 

public sealed class ClientOptions {
    public string? Username { get; set; }
    public string? Password { get; set; }
    public ReconnectPolicy ReconnectPolicy { get; set; } = new();
    public TimeSpan KeepAliveInterval { get; set; } = TimeSpan.FromSeconds(30);
    public TimeSpan CommandTimeout { get; set; } = TimeSpan.FromSeconds(10);
    public bool UseTls { get; set; }
    public bool SkipCertificateValidation { get; set; }
    public IReadOnlyList<CompressionAlgorithm> PreferredCompressions { get; set; }
        = [CompressionAlgorithm.Brotli, CompressionAlgorithm.GZip];
    public int CompressionThreshold { get; set; } = 1024;  // 1 KB
    public IList<QueueDeclaration> QueueDeclarations { get; set; } = [];
}

Username / Password

Type: string?

Default: null

Credentials for username/password authentication (new mode):

Username = "alice",
Password = "alice-secret"

Both Username and Password must be set together.

PreferredCompressions

Type: IReadOnlyList<CompressionAlgorithm>

Default: [Brotli, GZip]

Compression algorithms the client prefers (descending priority). Empty list disables compression. See Communication Protocol for negotiation.

CompressionThreshold

Type: int

Default: 1024 (1 KB)

Minimum serialized body size in bytes to apply compression. Bodies smaller than this are sent uncompressed.

ReconnectPolicy

Type: ReconnectPolicy

Reconnection policy:

ReconnectPolicy = new ReconnectPolicy {
    MaxAttempts = 10,
    InitialDelay = TimeSpan.FromSeconds(1),
    MaxDelay = TimeSpan.FromMinutes(5),
    UseExponentialBackoff = true
}

KeepAliveInterval

Type: TimeSpan

Default: 30 seconds

PING send interval:

KeepAliveInterval = TimeSpan.FromSeconds(60)

CommandTimeout

Type: TimeSpan

Default: 10 seconds

Command timeout:

CommandTimeout = TimeSpan.FromSeconds(30)

UseTls

Type: bool

Default: false

Use TLS:

UseTls = true

SkipCertificateValidation

Type: bool

Default: false

Skip certificate validation:

SkipCertificateValidation = true  // Tests only!

Warning

Do not use in production!

QueueDeclarations

Type: IList<QueueDeclaration>

Default: []

Queues to automatically create or verify on every ConnectAsync. Use the fluent DeclareQueue helper to populate this list:

new ClientOptions()
    .DeclareQueue("orders", q => {
        q.Mode            = DeliveryMode.FanOutWithAck;
        q.MaxQueueSize    = 50_000;
        q.MessageTtl      = TimeSpan.FromHours(24);
        q.EnableDeadLetterQueue = true;
    }, onConflict: QueueConflictResolution.Fail)
    .DeclareQueue("audit-log",
        onConflict: QueueConflictResolution.Ignore,
        failOnError: false)

Declarations are evaluated sequentially. See Client Usage for full details.

QueueDeclaration

Describes a single queue to provision at connection time.

public sealed class QueueDeclaration {
    public required string QueueName { get; init; }
    public QueueOptions Options { get; init; } = new();
    public QueueConflictResolution OnConflict { get; init; } = QueueConflictResolution.Ignore;
    public bool FailOnProvisioningError { get; init; } = true;
}

Property	Type	Default	Description
`QueueName`	`string`	required	Name of the queue to provision.
`Options`	`QueueOptions`	defaults	Desired queue settings.
`OnConflict`	`QueueConflictResolution`	Ignore	Strategy when Soft or Hard differences are found.
`FailOnProvisioningError`	`bool`	`true`	Abort `ConnectAsync` on provisioning errors. Set `false` to log and skip instead. Does not affect conflict handling.

QueueConflictResolution

Controls what happens when an existing queue has settings that differ from the declaration. Only Soft and Hard differences trigger this strategy; Info differences are always silently logged at Debug level.

public enum QueueConflictResolution { Ignore, Fail, Override }

Value	Behavior
`Ignore`	Keep the existing queue unchanged. Log the diff at Warning (Soft) or Error (Hard) level. Default.
`Fail`	Throw `QueueConflictException`. Treat settings drift as a deployment error. Recommended for production.
`Override`	Delete and recreate the queue with the declared settings. All existing messages are permanently lost. Use with caution.

ConflictSeverity

Severity level assigned to each setting difference.

public enum ConflictSeverity { Info, Soft, Hard }

Value	Logs	Description
`Info`	Debug	Additive or neutral change. Not a conflict; `OnConflict` is never triggered.
`Soft`	Warn	Behavioral change that may affect in-flight messages. `OnConflict` is applied.
`Hard`	Error	Breaking semantic change. `OnConflict` is applied.

ReconnectPolicy 

public sealed class ReconnectPolicy {
    public int MaxAttempts { get; set; } = int.MaxValue;
    public TimeSpan InitialDelay { get; set; } = TimeSpan.FromSeconds(1);
    public TimeSpan MaxDelay { get; set; } = TimeSpan.FromMinutes(5);
    public bool UseExponentialBackoff { get; set; } = true;
}

MaxAttempts

Type: int

Default: int.MaxValue

Maximum number of attempts:

MaxAttempts = 50

InitialDelay

Type: TimeSpan

Default: 1 second

Initial delay between attempts:

InitialDelay = TimeSpan.FromSeconds(2)

MaxDelay

Type: TimeSpan

Default: 5 minutes

Maximum delay:

MaxDelay = TimeSpan.FromMinutes(1)

UseExponentialBackoff

Type: bool

Default: true

Use exponential backoff:

UseExponentialBackoff = true

Health Check Configuration 

HealthCheckOptions 

public sealed class HealthCheckOptions {
    public bool Enabled { get; set; } = true;
    public int Port { get; set; } = 2926;
}

Enabled

Type: bool

Default: true

Enable health check server:

.ConfigureHealthChecks(options => {
    options.Enabled = true;
})

Port

Type: int

Default: 2926

HTTP port for health checks:

.ConfigureHealthChecks(options => {
    options.Port = 9090;
})

Configuration Examples 

Minimal 

var broker = BrokerBuilder.Create()
    .UsePort(2925)
    .Build();

Development 

var broker = BrokerBuilder.Create()
    .UsePort(2925)
    .UseAuthorization(options => {
    options.SuperuserUsername = "admin";
    options.SuperuserPassword = "dev-password";
})
    .ConfigureQueues(options => {
        options.DefaultDeliveryMode = DeliveryMode.RoundRobin;
        options.MaxQueueSize = 10_000;
        options.EnableAutoCreate = true;
    })
    .Build();

Production 

var broker = BrokerBuilder.Create()
    .UsePort(2925)
    .UseAuthorization(options => {
    options.SuperuserUsername = "admin";
    options.SuperuserPassword = Environment.GetEnvironmentVariable("VIBEMQ_SUPERUSER_PASSWORD");
})
    .UseMaxConnections(5000)
    .UseMaxMessageSize(2_097_152)
    .ConfigureQueues(options => {
        options.DefaultDeliveryMode = DeliveryMode.FanOutWithAck;
        options.MaxQueueSize = 100_000;
        options.EnableAutoCreate = true;
    })
    .ConfigureRateLimiting(options => {
        options.Enabled = true;
        options.MaxConnectionsPerIpPerWindow = 100;
        options.MaxMessagesPerClientPerSecond = 5000;
    })
    .UseTls(options => {
        options.Enabled = true;
        options.CertificatePath = "/etc/ssl/vibemq.pfx";
        options.CertificatePassword = Environment.GetEnvironmentVariable("CERT_PASSWORD");
    })
    .ConfigureHealthChecks(options => {
        options.Enabled = true;
        options.Port = 2926;
    })
    .Build();

IoT Scenario 

var broker = BrokerBuilder.Create()
    .UsePort(8883)
    .UseAuthorization(options => {
    options.SuperuserUsername = "admin";
    options.SuperuserPassword = "iot-password";
})
    .UseMaxConnections(10000)
    .ConfigureQueues(options => {
        options.DefaultDeliveryMode = DeliveryMode.RoundRobin;
        options.MaxQueueSize = 1000;
    })
    .ConfigureRateLimiting(options => {
        options.Enabled = true;
        options.MaxConnectionsPerIpPerWindow = 500;
        options.MaxMessagesPerClientPerSecond = 100;
    })
    .Build();

Microservices 

var broker = BrokerBuilder.Create()
    .UsePort(2925)
    .UseAuthorization(options => {
    options.SuperuserUsername = "admin";
    options.SuperuserPassword = "microservice-password";
})
    .ConfigureQueues(options => {
        options.DefaultDeliveryMode = DeliveryMode.FanOutWithAck;
        options.EnableAutoCreate = true;
        options.MaxQueueSize = 10_000;
    })
    .ConfigureHealthChecks(options => {
        options.Enabled = true;
        options.Port = 2926;
    })
    .Build();

With Authorization 

var broker = BrokerBuilder.Create()
    .UsePort(2925)
    .UseAuthorization(o => {
        o.SuperuserUsername = "admin";
        o.SuperuserPassword = Environment.GetEnvironmentVariable("VIBEMQ_ADMIN_PASS");
        o.DatabasePath = "/var/lib/vibemq/auth.db";
    })
    .UseMaxConnections(5000)
    .UseTls(options => {
        options.CertificatePath = "/etc/ssl/vibemq.pfx";
        options.CertificatePassword = Environment.GetEnvironmentVariable("CERT_PASSWORD");
    })
    .Build();

Next Steps 

Server Setup — server setup
Authorization — authorization and ACL
DI Integration — DI integration
Monitoring — monitoring