Servers

You can define multiple server sections in the configuration file. Each server section must have a unique name, which is used as the identifier in the [servers.<name>] format.

• Servers
  • Examples
  • Configuration
    • nickname
    • nick_password
    • nick_password_file
    • nick_password_file_first_line_only
    • nick_password_command
    • nick_identify_syntax
    • alt_nicks
    • username
    • realname
    • server
    • port
    • password
    • password_file
    • password_file_first_line_only
    • password_command
    • channels
    • channel_keys
    • order_channels_by
    • queries
    • ping_time
    • ping_timeout
    • reconnect_delay
    • should_ghost
    • ghost_sequence
    • umodes
    • use_tls
    • dangerously_accept_invalid_certs
    • root_cert_path
    • on_connect
    • anti_flood
    • who_poll_enabled
    • who_poll_interval
    • monitor
    • chathistory
    • proxy
    • autoconnect
  • Filters
  • SASL Plain
  • SASL External
  • Confirm Message Delivery

Examples

Examples can be found in the following guides:

• Example Server Configurations
• Multiple Servers
• Connect with soju
• Connect with ZNC

Configuration

nickname

The client’s nickname.

# Type: string
# Values: any string
# Default: not set

[servers.<name>]
nickname = ""

nick_password

The client’s NICKSERV password.

# Type: string
# Values: any string
# Default: not set

[servers.<name>]
nick_password = ""

nick_password_file

Read nick_password from the file at the given path.^{1 2}

# Type: string
# Values: any string
# Default: not set

[servers.<name>]
nick_password_file = ""

nick_password_file_first_line_only

Read nick_password from the first line of nick_password_file only.

# Type: boolean
# Values: true, false
# Default: true

[servers.<name>]
nick_password_file_first_line_only = true

nick_password_command

Executes the command with sh (or equivalent) and reads nick_password as the output.

# Type: string
# Values: any string
# Default: not set

[servers.<name>]
nick_password_command = ""

nick_identify_syntax

The server’s NICKSERV IDENTIFY syntax.

# Type: string
# Values: "nick-password", "password-nick"
# Default: not set

[servers.<name>]
nick_identify_syntax = ""

alt_nicks

Alternative nicknames for the client, if the default is taken.

# Type: array of strings
# Values: array of any strings
# Default: not set

[servers.<name>]
alt_nicks = ["Foo", "Bar"]

username

The client’s username.

# Type: string
# Values: any string
# Default: not set

[servers.<name>]
username = ""

realname

The client’s real name.

# Type: string
# Values: any string
# Default: not set

[servers.<name>]
realname = ""

server

The server to connect to. Should not contain the protocol, port, username, or password (i.e. should look like "irc.libera.chat" not "ircs://irc.libera.chat:6697").

# Type: string
# Values: any string
# Default: not set

[servers.<name>]
server = "irc.libera.chat"

port

The port to connect on. If you want to use a plain text port like 6667 you MUST also change the use_tls setting.

# Type: integer
# Values: any non-negative integer
# Default: 6697

[servers.<name>]
port = 6697

password

The password to connect to the server.

# Type: string
# Values: any string
# Default: not set

[servers.<name>]
password = ""

password_file

Read password from the file at the given path.^{1 2}

# Type: string
# Values: any string
# Default: not set

[servers.<name>]
password_file = ""

password_file_first_line_only

Read password from the first line of password_file only.

# Type: boolean
# Values: true, false
# Default: true

[servers.<name>]
password_file_first_line_only = true

password_command

Executes the command with sh (or equivalent) and reads password as the output.

# Type: string
# Values: any string
# Default: not set

[servers.<name>]
password_command = ""

channels

A list of channels to join on connection.

# Type: array of strings
# Values: array of any strings
# Default: not set

[servers.<name>]
channels = ["#foo", "#bar"]

channel_keys

A mapping of channel names to keys (passwords) for join-on-connect.

# Type: map
# Values: map with string key value
# Default: {}

[servers.<name>]
channel_keys = { "#foo" = "password" }

order_channels_by

Ordering for channels listed in the sidebar for the current server.

• "name": Sort channels by name only, ignoring chantypes (channel prefixes, e.g., # and ##).
• "name-and-prefix": Sort channels by name including their chantypes.
• "config": Sort channels in the order they appear in your server’s channels list. Any channels not in the list appear last, using default ("name") sort.

If not set, the value will be taken from the sidebar config: order_channels_by.

# Type: string
# Values: "name", "name-and-prefix", "config"
# Default: "name"

[servers.<name>]
order_channels_by = "config"

# Example: When using "config", channels appear in this exact order:
channels = ["#rust", "#halloy", "#halloy-test"]
# Result: #rust → #halloy → #halloy-test → (any other channels are sorted by "name")

queries

A list of queries to add to the sidebar on connection.

# Type: array of strings
# Values: array of any strings
# Default: not set

[servers.<name>]
queries = ["alice", "bob"]

ping_time

The amount of inactivity in seconds before the client will ping the server.

# Type: integer
# Values: any non-negative integer
# Default: 180

[servers.<name>]
ping_time = 180

ping_timeout

The amount of time in seconds to wait for a ping response before attempting to reconnect.

# Type: integer
# Values: any non-negative integer
# Default: 20

[servers.<name>]
ping_timeout = 20

reconnect_delay

The amount of time in seconds before attempting to reconnect to the server when disconnected.

# Type: integer
# Values: any non-negative integer
# Default: 10

[servers.<name>]
reconnect_delay = 10

should_ghost

Whether the client should use NickServ GHOST to reclaim its primary nickname if it is in use.

# Type: boolean
# Values: true, false
# Default: false

[servers.<name>]
should_ghost = false

ghost_sequence

The command(s) that should be sent to NickServ to recover a nickname.

# Type: array of strings
# Values: array of any strings
# Default: ["REGAIN"]

[servers.<name>]
ghost_sequence = ["REGAIN"]

umodes

User modestring to set on connect.

# Type: string
# Values: any string
# Default: not set

[servers.<name>]
umodes = "+RB-x"

use_tls

Whether or not to use TLS. Clients will automatically panic if this is enabled without TLS support.

# Type: boolean
# Values: true, false
# Default: true

[servers.<name>]
use_tls = true

dangerously_accept_invalid_certs

When true, all certificate validations are skipped.

# Type: boolean
# Values: true, false
# Default: false

[servers.<name>]
dangerously_accept_invalid_certs = false

root_cert_path

The path to the root TLS certificate for this server in PEM format.^{1 2}

# Type: string
# Values: any string
# Default: not set

[servers.<name>]
root_cert_path = ""

on_connect

Commands which are executed once connected, in the order they are specified. The /delay <seconds> command can be used to add a delay between commands.

# Type: array of string
# Values: array of any strings
# Default: not set

[servers.<name>]
on_connect = ["/msg NickServ IDENTIFY foo bar", "/delay 2", "/join registered-club"]

anti_flood

The time (in milliseconds) between sending messages to servers without SAFERATE. Timing is not strictly guaranteed; small groups of messages may be allowed to be sent at a faster rate, messages may be delayed in order to be batched, automated messages are included in the queue (most at a lower priority than user messages), etc.

# Type: integer
# Values: 100 .. 60000
# Default: 2000

[servers.<name>]
anti_flood = 2000

who_poll_enabled

Whether or not to WHO polling is enabled.

# Type: boolean
# Values: true, false
# Default: true

[servers.<name>]
who_poll_enabled = true

who_poll_interval

WHO poll interval (in seconds) for servers without away-notify. Specifically, the time between individual WHO requests. Will be increased automatically if the server sends a rate-limiting message. When the server does not support SAFERATE (and anti-flood protections are enabled) then who_poll_interval will be increased to more than twice anti_flood if it is not already.

# Type: integer
# Values: 1 .. 3600
# Default: 2

[servers.<name>]
who_poll_interval = 2

monitor

A list of nicknames to monitor (if IRCv3 Monitor is supported by the server).

💡 Read more about monitoring users.

# Type: array of string
# Values: array of any strings
# Default: not set

[servers.<name>]
monitor = ["Foo", "Bar"]

chathistory

Whether or not to enable IRCv3 Chat History (if it is supported by the server).

# Type: boolean
# Values: true, false
# Default: true

[servers.<name>]
chathistory = true

proxy

Custom proxy for specified server

The logic is as follows:

• If a server proxy is provided, it will be used.
• If a server proxy is not provided, the global proxy will be used.
• If the global proxy is not provided, a plain connection will be used.

The configuration syntax and supported proxy types are similar to the global Proxy but associated with the current servers.<name>:

[servers.<name>.proxy.http]
host = "192.168.1.100"
port = 1080
username = "username"
password = "password"

or

[servers.<name>.proxy.socks5]
host = "192.168.1.100"
port = 1080
username = "username"
password = "password"

autoconnect

Whether or not to connect to the server when launching Halloy or when changing the connection details in the server configuration.

# Type: boolean
# Values: true, false
# Default: true

[servers.<name>]
autoconnect = true

Filters

Filter messages based on various criteria

SASL Plain

Plain SASL auth using a username and password

SASL External

External SASL auth uses a PEM encoded X509 certificate.

Confirm Message Delivery

Whether and where to confirm delivery of sent messages, if the server supports echo-message

1. Windows path strings should usually be specified as literal strings (e.g. 'C:\Users\Default\'), otherwise directory separators will need to be escaped (e.g. "C:\\Users\\Default\\"). ↩ ↩2 ↩3

2. Relative paths are prefixed with the config directory (i.e. if you have your config.toml in /home/me/.config/halloy/config.toml, path .passwd/libera will be converted to /home/me/.config/halloy/.passwd/libera). ↩ ↩2 ↩3