Why a Graylog load balancer setup needs input-level decisions
A load balancer in front of a Graylog cluster gives users and log sources one stable address, but it does not treat every type of traffic the same way. The short answer is that the web interface and REST API can sit behind a standard HTTP balancer with health checks, while each network input needs its own decision about which nodes receive traffic, whether it runs on every node or only one, and whether a balancer should be involved at all. Graylog's multi-node guide recommends three Graylog nodes with MongoDB as a replica set, three Data Nodes on their own cluster, a load balancer, and is_leader set to false on follower Graylog nodes. That layout is the starting point, not the finished design.
The web interface and REST API are request-response traffic. Users and automation clients can reach any healthy Graylog node, and the address they use must match what the nodes advertise, which is controlled by http_external_uri. If that value points at the balancer but the nodes still advertise their own addresses, links, redirects and browser sessions can break in ways that look like application faults. Confirm the value on every node before you test the balancer, and confirm that your health check targets an endpoint that reflects node readiness rather than a bare TCP port check.
Inputs are different because log senders open long-lived connections or send datagrams, and each input runs on the nodes where it is configured. Spreading a TCP syslog or GELF input across nodes can work well, but UDP traffic has no session to rebalance, and some sources, such as IPFIX flow exporters, expect a stable exporter-to-collector relationship. Before you place any input behind the balancer, decide whether it should be global (running on all nodes) or local (running on one node), and check which protocols the balancer you chose can forward. Confirm these details against the Graylog input documentation for your version and against your balancer's UDP support, because they determine which settings you change next.
Load balancer options for Graylog traffic
This table compares the configuration and balancing choices that shape how web, API and input traffic reaches Graylog nodes. Read each row for the situation where the option fits and the failure that follows when it is set wrong. The main takeaway is that the web interface, the API and log inputs need different treatment, so one generic proxy setup usually fails at least one of them.
| Option | When it fits | What breaks if it is wrong |
|---|---|---|
| http_external_uri | Users and API clients reach Graylog through a load balancer or DNS name that differs from the node address | Browser redirects and links point at a node address or wrong host, so sessions and API callers fail or bypass the balancer |
| http_bind_address | Each Graylog node should listen on an interface the balancer can reach, such as a private network address | Nodes bind to a loopback or unreachable interface, so health checks fail and the balancer marks every node down |
| Layer 4 (TCP) balancing | Passing HTTPS through to Graylog without inspecting it, or balancing raw TCP inputs such as syslog over TCP | Without a layer 7 view, the balancer cannot route by path or read HTTP health responses, so it cannot tell an unhealthy web service from a reachable port |
| Layer 7 (HTTP) balancing | Routing the web interface and REST API by host or path, applying health checks on an HTTP endpoint and setting session affinity | TLS termination, header forwarding or path rules that differ from http_external_uri cause login loops, mixed content or API errors |
| Sticky sessions for the web interface | Browser sessions must stay on one node for the duration of a login, which is the usual case for the web interface | Without affinity, a session can move between nodes and users are asked to sign in again; affinity applied to API clients can concentrate their load on one node |
| Health check endpoint | Confirm each node serves the web and API before it receives traffic, and remove failed nodes from rotation | A check that only tests the TCP port passes on a node whose web service is down; a check against a path that requires authentication marks healthy nodes as failed |
| TCP input listeners | Syslog over TCP or GELF over TCP where connections are long-lived and ordering matters within a connection | A connection is pinned to one node, so load can be uneven; if a node leaves, the sender must reconnect and may need retry settings |
| UDP input listeners | Syslog or other datagram sources that send without connections and can tolerate some loss under pressure | Datagrams sent to a balancer that does not forward UDP correctly are dropped silently, and bursts can overflow a node without any visible error at the sender |
| Global versus local inputs | A global input should run on every node so any node can receive traffic; a local input is bound to one node by design | A local input behind a balancer receives traffic only on the node that runs it, so senders see gaps; a global input on a node set that does not match the balancer pool sends logs to unreachable listeners |
| Inputs that should not be spread across nodes | Flow exporters such as IPFIX, where template state is tied to the exporter and a source should reach one listener consistently | Spreading template-based flows across nodes can leave a node without the templates it needs to decode records, so data appears as unreadable or missing |
Global versus local inputs behind a balancer
A Graylog input is configured once, but its scope decides where it runs. A global input starts on every Graylog server node in the cluster, so any node can accept traffic that the balancer sends to it. A local input starts on only one node, which means only that node listens for its traffic. The scope matters most when a balancer sits in front of the inputs, because the balancer assumes that any healthy node can answer a connection.
- Global inputs: every node opens the listener, so the balancer can distribute senders across all of them.
- Local inputs: one node opens the listener, so traffic must reach that specific node, usually by a fixed address rather than a shared virtual address.
- Scope is a per-input setting: a cluster can run global and local inputs side by side, so review each input separately.
- Failover depends on scope: a global input keeps receiving when one node fails, while a local input stops until its node returns or the input is moved.
Confirm how your Graylog version exposes the global setting and where it appears in the input configuration before you design the balancer pools.
Syslog is the input most often pointed at a shared address, because network devices, firewalls and servers usually accept only one destination. That makes syslog a strong candidate for a global input behind a balancer. The choice still depends on the transport the sender uses and whether the sender keeps a connection open, since a balancer can only spread new connections or datagrams, and it cannot fix a sender that stays pinned to one address.
- Sender limits first: check whether each device lets you set a hostname or virtual address, or only a fixed IP.
- Transport choice: TCP streams keep a session with one node, while UDP datagrams are independent, so behavior under failover differs.
- Dropped messages on failover: UDP has no delivery acknowledgment, so confirm how much loss your sources can tolerate during a node restart.
- Parsing consistency: if a global syslog input feeds the same pipelines on every node, confirm that the parsing rules are identical across nodes.
- Shared sources: keep an inventory of which devices use the virtual address, so a port change does not orphan them.
Confirm the device-side destination settings and test a failover with one non-critical source before moving production senders.
GELF and Beats senders are usually applications, agents or shippers that you configure directly, so you control their destinations. Many teams run these inputs as global inputs so each node can accept traffic from a balancer pool. Some sources still need a local input, for example when a sender cannot reach a shared address, or when a feature in your Graylog version works only on one node. Decide per input after checking the sender's connection model.
- Application senders: GELF clients and log shippers that accept a list of servers can often point at the balancer, so they benefit from global inputs.
- Agent-managed hosts: Beats agents keep connections open and retry on failure, so confirm how they handle a node going away mid-stream.
- Acknowledgments: check whether each sender waits for acknowledgment from the receiver, since that determines how a failed node affects delivery.
- Certificates on the balancer: if you terminate TLS at the balancer, confirm which senders trust that certificate.
- Per-node exceptions: where a local input is needed, document the node that owns it and its recovery steps.
Confirm each sender's retry and failover behavior, and test with one source of each type before applying the scope to the whole fleet.
When senders use one virtual address for an input, the balancer forwards their traffic to whichever node is healthy at that moment. That only works if every node that receives the traffic listens on the same port for that input. If one node uses a different port, or does not run the input at all, the balancer sends it traffic that it cannot accept, and those messages are lost or refused. Consistency across nodes is therefore a requirement, not an option.
- Same protocol and port: configure each global input with the same transport and port on every node.
- Firewall rules on each node: open the input port on every node, not only on the one you configured first.
- Health checks on the input: a balancer check on the web interface does not prove that the input port is accepting traffic, so add a check that targets the input.
- Node additions: a new node joins with the inputs it receives from the cluster configuration, so confirm that the new node starts the same listeners.
- Change control: treat a port change as a coordinated change across all nodes and the balancer pool.
Before go-live, send a test message to the virtual address for each input and confirm that it arrives from every node in turn. For the wider cluster layout, see the Graylog multi-node installation guide.
Inputs that should not be spread across nodes
Not every Graylog input behaves the same behind a load balancer. Some inputs keep state on the node that receives the traffic, and others expect a single sender or a single listener. Test each input against its documented behavior before you point production traffic at the balancer.
IPFIX flow exporters
IPFIX exporters send template records that describe how to read later data records, and the template state is kept per exporter and per session. If a balancer spreads one exporter across several Graylog nodes, a node that never saw the template cannot decode the data records that follow. Pin each exporter to one node, or run the IPFIX input on a single node, and confirm how the input handles template refresh and restarts in the version you run.
Single-source feeds
Some feeds come from one sender that writes to one listener, such as a vendor appliance that accepts only one syslog destination or a file-based collector that tails a single log. If the balancer rotates connections across nodes, the same events can be indexed twice or the sender can fail over mid-stream and create gaps. Give these feeds a fixed target address and verify the sender's failover behavior in its own documentation.
Local inputs with node-specific sources
A local input is bound to one node, so it only receives traffic that reaches that node. Use a global input when every node should accept the same traffic, and a local input when the source must reach a particular node, such as a collector on a segment that only one Graylog server can reach. Map each input to its scope on purpose, because a local input placed behind a balancer will receive only part of the traffic.
UDP inputs with sender affinity
UDP has no connection, so a balancer usually distributes datagrams by source address and port. Some senders reuse one source port for all traffic, which can send the whole feed to one node and defeat the spread you planned. Confirm how your balancer hashes UDP, then load test a representative sender to see which node receives traffic and whether the receiving nodes keep up.
Inputs that depend on a fixed listener identity
Some sources authenticate or allowlist a specific IP address or hostname for the receiving side. When the balancer or a node changes, the sender may reject the connection or send to an address that no longer answers. Decide which address the sender will use, keep it stable through maintenance, and record which inputs require it so that node replacements do not silently break delivery.
Setting up the load balancer step by step
This sequence takes a multi-node Graylog cluster from its MongoDB and node layout to a working entry point, where the web interface, API and inputs answer through the balancer and every source type has been tested on each node. Each step ends with a check, so problems surface before logs from production sources depend on the setup.
Confirm the cluster layout and MongoDB replica set
Before touching the balancer, confirm that the Graylog server nodes, the MongoDB replica set and the Data Node cluster match the layout Graylog documents for medium to large deployments. That layout uses three Graylog and MongoDB nodes, MongoDB as a replica set, and three Data Nodes on their own cluster. Your infrastructure or platform team should verify each node's hostname, network reachability between nodes, and that the replica set reports a healthy primary. The step is done when every Graylog node can reach MongoDB and the Data Node cluster, and the replica set shows one primary with the expected members.
Set leader role on follower nodes
Exactly one Graylog node should act as the leader, and the others should have is_leader set to false in their server configuration. Your platform team edits the configuration file on each follower node, restarts the Graylog service on that node, and records which node holds the leader role. The check is that the Graylog system overview shows one leader and that the followers report as non-leaders. Confirm the setting on each node before you move on, because a mismatch here can cause duplicate work across the cluster.
Set http_external_uri to the balancer address
Set http_external_uri in the server configuration on every Graylog node to the address users and integrations will use to reach the balancer, including the scheme and the path the web interface is served on. Restart each node after the change. The check is that the links Graylog generates in the web interface, such as those in notifications and shared views, point to the balancer address rather than an individual node. Confirm the value with the team that owns the DNS record and the certificate for that name before you publish it.
Configure the balancer pool and health checks
Create a pool on your balancer that lists every Graylog node, and attach a health check to the web interface port so the balancer only sends web and API traffic to nodes that respond. Your network or platform team owns this configuration, and the exact settings depend on the balancer product you use. For TCP and UDP inputs, plan the pool separately, because inputs bind to ports on each node and are covered in the next step. The check is that each node in the pool shows as healthy and that stopping one node's Graylog service removes it from rotation without breaking the web interface.
Create inputs with the chosen scope
Create each input as a global input when every node should listen on the same port, or as a local input when only one node should receive that traffic. Inputs such as IPFIX that are tied to a specific exporter or flow relationship usually belong on one node, not spread across the cluster, so confirm the scope for each input against the source's behavior. Your Graylog administrator makes the change in the system settings and records the scope in your runbook. The check is that each node shows the input as running, and the local inputs appear only on the node you chose.
Send test traffic from each source type
Send test messages from every source type you plan to use, such as syslog over TCP and UDP, GELF, Beats or another input, and direct each test through the balancer address or the port the balancer forwards. Run tests more than once so traffic reaches different nodes, and confirm the messages appear in search. Your team should also check the input status on each node after the tests. The check is that each test message is searchable, appears on the expected node for local inputs, and the input metrics show traffic on every node that should receive it.
Confirm web and API access through the balancer
Finish by logging in to the Graylog web interface through the balancer address and running a search, then calling the Graylog API through the same address with a test request. Use a user account that matches your authentication setup, since Graylog Open supports Active Directory, LDAP and trusted header authentication. Repeat the login after stopping one node to confirm the session keeps working through the remaining nodes. The step is done when the interface loads, searches return results and the API responds consistently across node failures you have tested.
Security and operational considerations for the balancer
A load balancer in front of Graylog becomes a trust boundary, a log source and a point of failure at the same time. The cards below cover the decisions that keep traffic protected, input ports reachable only from intended sources, and each node's health visible.
TLS termination or pass-through
Decide whether the balancer terminates TLS for the web interface and API or passes encrypted traffic through to the Graylog nodes. Termination is simpler to certify and renew, but the hop from balancer to node must then be protected by a network boundary you control. Confirm the http_external_uri value matches the public address users actually reach, or redirects and links break. Check the transport settings in the Graylog security documentation before choosing.
Restrict who reaches input ports
Inputs such as syslog and GELF listen on their own ports, and a balancer exposing them widens who can send data to Graylog. Allow only known source ranges from hosts, network devices and collectors to each input port, both at the balancer and in host firewalls on each node. Treat UDP inputs as unauthenticated unless your sender network already restricts them. Document each allowed source so an unexpected sender shows up as a change.
Keep health checks off authenticated pages
A health check that requests a login-protected page either fails when sessions expire or forces the balancer to hold credentials. Point the balancer at a node status endpoint that does not need a user session, and confirm the endpoint in your Graylog version before relying on it. Restrict that endpoint to the balancer's addresses so it discloses no more than necessary. Test the check by stopping one node and confirming traffic moves to the others.
Retain balancer access logs deliberately
Balancer access logs record client addresses, requested paths and response codes for the web interface and API. Decide how long they are kept and where, and do not send them into the same Graylog streams as application logs without a retention rule, since they can grow quickly and contain personal data. Apply the same retention and access rules you set for other security records. Confirm the storage location and retention period with your compliance owner before go-live.
Monitor journal and input status per node
Each Graylog node holds its own message journal and runs its own inputs, so a healthy balancer can hide a node that is backing up or has stopped receiving. Check journal utilization and input state on every node, not only through the balancer. The Graylog system architecture guidance on sizing the journal on SSDs is the baseline to compare against. Alert when a journal grows steadily or an input stops, and make the check part of your routine review.
Separate node roles for leader handling
In a multi-node setup, follower nodes must have is_leader set to false so that only the intended node performs leader duties. A balancer that routes admin work to a follower with the wrong setting can produce confusing behavior that is hard to trace. Record which node is the leader in your runbook, and verify the setting on every node after each configuration change. Include this check in upgrade and failover tests.
Questions teams ask before setting up a Graylog load balancer
How much effort does a Graylog load balancer setup take?
The effort depends on how many Graylog server nodes sit behind the balancer, how many inputs you publish, and which protocols they use. A basic setup for the web interface and API is a small piece of work. Inputs add more: each TCP or UDP port needs a listener, a health check or source-side failover plan, and a decision on whether the input runs on every node or on one. The main drivers are:
- Number of Graylog server nodes and whether follower nodes have
is_leaderset to false - Count and type of inputs, especially UDP syslog and any protocol that holds state
- Certificates, DNS and the
http_external_urivalue that clients and browsers use - Testing from each real source, including failover and a node restart
Ask any partner to break the estimate into these four items.
Can our own team set up a Graylog load balancer without a partner?
Yes, a team with experience in load balancers, Linux networking and Graylog administration can build it in-house. The Graylog multi-node guide describes the building blocks: three Graylog and MongoDB nodes, a replica set, three Data Nodes, a load balancer, and is_leader set to false on follower nodes. The harder parts are input behavior and testing, because some sources resend or fail over differently than others. Choose a partner when your team lacks load balancer or input experience, when the input list is long, or when you need a documented test record for an audit. The Graylog multi-node installation guide is the right starting point for your own plan.
What do our network and security teams need to provide?
Plan these items with your network and security teams before the build starts:
- A DNS name and TLS certificate for the web interface and API, and the matching
http_external_urivalue - Firewall rules that allow sources to reach the balancer's listener ports, and that allow the balancer to reach each Graylog node
- An approved source list for each input, so only expected hosts and devices can send logs
- Access for health checks and for the monitoring tools that will watch the listeners
- A change window for the cutover, and a rollback plan for sources that point at the old address
Security reviewers will also ask how the balancer handles TLS, which ports stay open, and where logs about the balancer itself are kept.
How long does a Graylog load balancer project take?
No duration applies to every environment, so ask for one based on your own inventory. Timing grows with the number of inputs, the number of distinct source types, and the number of teams that must approve changes. A small set of web and API endpoints with two or three syslog sources moves faster than a project with many network devices, cloud sources and UDP feeds, each needing its own test. Ask a partner to show the planned phases: design, build in a test environment, source-by-source testing, cutover and a short observation period. Under a fixed scope, the agreed written plan sets the timeline.
Does Graylog Open support every input we need behind a load balancer?
Graylog Open ingests logs over inputs such as syslog, GELF and Beats, so many common sources work without a commercial license. Whether a given input can run across nodes depends on the input type and how the source sends data, so check each one against the Graylog documentation for your version. Some inputs and features need Enterprise or Security licensing, and the Graylog pricing page lists those tiers. The Graylog Open product page describes what the open edition includes. Graylog Open is licensed under SSPL-1.0, which is not an OSI-approved open source license, so confirm that this license fits your organization's policy before you commit.
What does a fixed-scope Graylog load balancer engagement cover?
A fixed-scope engagement lists the scope, deliverables and timeline in writing before work starts. DeployOpen plans, implements, documents and tests the setup inside your own infrastructure. Typical written items include the architecture for the balancer and Graylog nodes, the http_external_uri and listener configuration, a per-input decision record, health check settings, a test matrix with results, and a runbook for your team. Ask the quote to name each input in scope, the number of nodes, the test environment, and what is excluded, such as source reconfiguration on devices you do not manage. Ongoing support and upgrades can be added as a retainer.
What should we ask for in a Graylog load balancer quote?
Ask for a quote that matches your written inventory, so each price line maps to a clear item. Request these items explicitly:
- A list of every input, its protocol, its source and whether it runs on all nodes or one
- The node count, test environment and cutover approach
- Who makes source-side changes, and who approves firewall and DNS work
- Which items are one-time build work and which recur, such as monitoring review or upgrades
- Assumptions about your environment and what happens if they change
DeployOpen does not publish a price list, so the written scope is the basis for every quote.
How DeployOpen scopes and delivers Graylog load balancing
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, including the load balancer layer in front of Graylog. Engagements run against a written scope, so the web interface, API and input paths are agreed, built and tested before go-live.
How we scope
- Inventory which clients use the web interface, the REST API and each input type, and map each to a listener port and protocol.
- Confirm the http_external_uri value, TLS termination point and certificate ownership for the Graylog web and API hostnames.
- Agree in writing which inputs run as global and which as local, and which UDP or IPFIX sources stay pinned to one node.
How we build
- Configure the load balancer pool across Graylog nodes, with health checks against the server API and per-protocol forwarding rules.
- Set is_leader to false on follower nodes and confirm that only the intended node holds leadership before traffic is routed.
- Test each input path under load and failover, recording which node receives each source and how the message journal behaves.
How we hand over
- Deliver the load balancer configuration, input placement map, health check definitions and the reasons behind each routing choice.
- Provide a runbook covering node removal, certificate renewal, adding nodes and re-pinning sources that send to a fixed node.
- Walk your operations team through failover tests and the evidence collected, so they can repeat the checks themselves.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing are available as a retainer, including re-checking routing after Graylog upgrades.
- Ask any partner for the written scope, the named deliverables and the retainer terms before comparing quotes with your own team's effort.
