Graylog 6.1, 6.2 and 6.3 upgrades: why the path matters
If your Graylog deployment is on 5.2 or an early 6.x release, move forward one minor version at a time: 6.0, 6.1, 6.2, 6.3, then 7.0. Graylog advises this sequence, and 6.1, 6.2 and 6.3 are the steps that sit between your current release and the 7.0 upgrade. Skipping a step means your team has to absorb the breaking changes of several releases in a single change window, and it becomes hard to tell which change caused a failure in your automation, roles or parsing.
The 6.x minor releases carry few breaking changes, but the ones they carry are specific and easy to miss. They touch API error types, a removed built-in data adapter, role requirements for Enterprise reports and permissions for input types. Each one can break a script, a dashboard or a user's access without any visible error in the Graylog interface. Read the upgrade notes for each release in order and list which of your integrations, service accounts and workflows touch the affected areas before you change any version number. Confirm with your own inventory, not memory, which of these you use.
Graylog Open is licensed under the Server Side Public License version 1 (SSPL-1.0), which is not an OSI-approved open source license. That does not change the upgrade mechanics, but it does mean the upgrade is run by your team on infrastructure you control, with your own backups, test environment and rollback plan. Confirm the license terms that apply to your edition and whether any inputs or features you rely on need an Enterprise license before you plan the path.
What changes in each 6.x minor release
This table lists the documented changes in Graylog 6.1, 6.2 and 6.3 and what each one affects for scripts, dashboards and users. Read each row against the release you are stepping onto, then work through the action column before starting that minor upgrade. The main takeaway is that the 6.1 change to API error types and the 6.3 permission changes are the ones most likely to break automation or hide reports from users.
| Release and change | Impact | Action needed |
|---|---|---|
| 6.1: API error type | Invalid-request responses now return RequestError instead of APIError, so client code that matches on the old type can fail. | Search scripts and API clients for APIError handling and update them to expect RequestError before upgrading. |
| 6.1: GreyNoise Community adapter removed | The GreyNoise Community Data Adapter, deprecated in 5.2, is no longer available, so any lookup or enrichment that relied on it stops working. | Find lookup tables, pipelines or dashboards that reference the adapter and replace the enrichment source before the upgrade. |
| 6.2: Documented changes | Impact depends on the release notes, which should be read directly before planning this step. | Confirm the changes listed in the Graylog 6.2 upgrade notes and map each one to your scripts, dashboards and users before scheduling 6.2. |
| 6.3: Report creator role | From 6.3, users need the report creator role to create Enterprise reports, so users who build reports today may lose that ability. | Identify report authors, assign the report creator role where appropriate and confirm the change applies to your Enterprise license. |
| 6.3: Input type permissions | The input_types:create permission can restrict users to specific input types, so users who add inputs today may be blocked from some types. | Review which users and roles create inputs, decide which input types each group needs and grant input_types:create only where intended. |
Why each minor version is a separate step
Graylog advises upgrading one minor version at a time, so a move from 5.2 to 7.1 is not a single jump but a sequence of stops: 6.0, 6.1, 6.2, 6.3, then 7.0 and 7.1. The reason is practical. Each minor release can change API behavior, plugin expectations, parsing or permissions, and the upgrade notes for each stop describe those changes. A team that skips a stop loses the chance to test one set of changes in isolation, and a failure at the far end becomes hard to trace to a cause. Plan the path as a written list of stops before the first change is made, and agree who signs off each one.
At every stop, confirm three things before moving on. First, the Graylog version you are moving to is compatible with your current MongoDB and search backend, checked against the Graylog compatibility matrix rather than from memory. Second, the Data Node or OpenSearch version is inside the range that release supports, since a Graylog minor step can change that range. Third, the upgrade notes for that specific release have been read against your own configuration, including automation that calls the API, custom plugins and dashboards. Record the result of each check so that the next stop starts from a known state, and confirm that inputs are flowing and the message journal drains before proceeding.
The step from 6.x to 7.0 is a separate project with its own dependencies, including Java, MongoDB and Data Node requirements and API changes that affect automation. It is covered on its own page, and it should not be folded into the 6.3 work described here. Treat 6.3 as the last checkpoint of this path: once the cluster runs cleanly on 6.3 with the changes below verified, the 7.0 planning can start from a stable baseline. Confirm the exact prerequisites for 7.0 against the official upgrade documentation when you reach that stop, because they may differ from what you expect after the 6.x work.
What to prepare before the first 6.x step
Stepping through the 6.x minor releases starts with a known-good recovery point, a complete list of what depends on changed behavior, and a test environment that behaves like production. The four cards below cover the items that most often decide whether the first step runs cleanly or stalls halfway.
Full backup of configuration
Take a complete backup of the MongoDB database that holds Graylog configuration and metadata, along with the server.conf file on every Graylog node. Restoring from this backup is the only reliable way to return the configuration to its prior state if a minor upgrade fails. Confirm that you can restore it into a scratch environment before you begin, because an untested backup is not a recovery plan. Log-data indices are a separate concern and should be planned for under your storage policy.
Inventory of changed behavior
List every custom plugin, API client, script and dashboard that calls the Graylog API. In 6.1, invalid-request errors are returned as RequestError instead of APIError, so any code that matches on the old error type will misbehave. Note any reference to the GreyNoise Community Data Adapter, which 6.1 removes. The inventory should name the owner of each item so that fixes can be scheduled before the step that breaks them.
Production-like test environment
Build a test environment that mirrors production inputs, streams, processing pipelines, event definitions and index set settings. Replay representative traffic through the same inputs and confirm that parsing, routing and alerts produce the same results on each 6.x version. Include the MongoDB and search backend versions your current release uses, because the compatibility matrix defines supported combinations per Graylog release. Treat any difference in output as a blocker until it is explained.
Enterprise license scope
Confirm which of your users need the report creator role, which is required from Graylog 6.3 to create Enterprise reports. Also confirm whether you plan to use the input_types:create permission to limit users to specific input types. Both features depend on your license edition, so check the scope of your current license before assuming they are available. Record the result, because role assignments and input restrictions must be set up in the same window as the 6.3 step.
Upgrade sequence for each minor release
This sequence moves a Graylog deployment through 6.1, 6.2 and 6.3 one minor release at a time, so each stop has a verified state and a rollback point before the next change. Each step closes with a check the team can record.
Back up the current state
Before touching any package, the operations owner takes a full backup of the Graylog configuration, the MongoDB database that holds configuration and metadata, and the Data Node or OpenSearch indices that the team cannot rebuild from source. Confirm the backup restores in a test environment, not only that the backup job reported success. Record the current Graylog server version, package versions and backup identifier in the change record. The step is done when a restore has been tested and the change record holds the rollback point for this stop.
Confirm the target version prerequisites
Read the upgrade notes for the target minor release, starting with the Graylog 6.1 upgrade guide, and compare them against the Graylog compatibility matrix for the MongoDB and Data Node or OpenSearch versions in place. Check the operating system packages, Java runtime and any plugins you run. Ask the Graylog vendor or your support contact to confirm anything the notes leave open for your configuration. The step is done when a written list of prerequisites shows each item as met, with the version evidence attached.
Upgrade one node in a test environment
The platform engineer rebuilds a test environment from the production backup and upgrades a single Graylog node to the target minor release, following the installation and upgrade documentation for your deployment method. Start the node, watch its startup logs for errors on configuration keys and plugins, and confirm it joins the cluster and serves the web interface. The step is done when the test node runs the target version with no startup errors that the team has not explained and resolved.
Check API consumers and reports
Before any production change, the integration owner runs the scripts, automations and API clients that call Graylog against the test node and compares their responses with the previous version. For 6.1, look for invalid-request errors that now arrive under a different error type, and confirm that nothing depends on the GreyNoise Community Data Adapter that 6.1 removed. For 6.3, confirm that users who create Enterprise reports hold the report creator role, and that roles restricted by input type permissions still reach the inputs they need. The step is done when each consumer has a pass result or a documented fix.
Upgrade production nodes and verify journal and inputs
Apply the same upgrade to production, one node at a time, and follow the multi-node upgrade guidance for node order, backend timing and keeping inputs flowing through the message journal. After each node restarts, check that the journal drains and does not keep growing, that each input reports running and receiving messages, and that searches return recent data. Hold the next node until those checks pass. The step is done when every node runs the target version and the journal and input checks are recorded as passing.
Verify the stop before moving on
Once all nodes run the target version, the operations owner reviews a day of live operation against the baseline recorded before the upgrade. Confirm that alerts fire as expected, dashboards load, scheduled reports run and no integration has failed silently. Record the verified version and a fresh backup as the rollback point for this stop. The step is done when the change record shows a verified state and a new backup taken after the upgrade.
Roll forward to the next minor release
Only after the previous stop is verified, the team starts the sequence again with the next minor release, moving from 6.1 to 6.2 and then from 6.2 to 6.3. Graylog advises upgrading one minor version at a time, so do not skip a stop even when a later release looks like it contains the changes you need. Repeat the backup, prerequisite, test node, consumer, production and verification steps for each release. The step is done when the deployment runs 6.3 with a verified rollback point for each stop along the way.
How to roll back a failed minor upgrade
Rollback for a Graylog minor upgrade is only as good as the state you can put back. Before the change window, confirm that you hold a verified MongoDB backup taken immediately before the upgrade, and that you still have the exact previous Graylog package or container image for the version you are leaving. Rolling back the Graylog binaries alone is not enough, because the configuration and metadata that Graylog keeps in MongoDB, including streams, pipelines, event definitions and users, may have been changed by the newer server during its first start. Restoring the MongoDB snapshot is what returns that metadata to the earlier state, so store the backup somewhere the upgrade itself cannot touch.
The second constraint is the log data. Graylog writes indices into the search backend, either Graylog Data Node or self-managed OpenSearch, and the version you roll back to must still be able to read and search those indices. Check the compatibility matrix for the restored version before you start, and test a search against an index written by the new release in a non-production copy. Also confirm whether any index set settings, template changes or journal contents were modified during the upgrade, since a restored server may not expect them. Treat the message journal as a risk during rollback, because messages still in it may be processed by a different version than the one that wrote them. The exact rollback sequence, including whether a particular minor release supports a downgrade path at all, is not something to reconstruct from memory. Confirm the rollback steps in the official upgrade documentation for your target version, starting with the Graylog upgrade documentation, and rehearse them on a copy of your environment. Record who approves a rollback decision and the point at which you will stop trying to fix forward, so the team does not spend the change window debating it.
How the upgrade differs by deployment model
On a single Graylog server installed from Debian or RPM packages, the Graylog server, its MongoDB and its search backend usually run on one host or a small set of hosts that your team maintains directly. No other Graylog node takes over work during the change, so the upgrade is a sequence of package and service steps on one machine. The main risk is that inputs such as syslog and GELF keep accepting messages while the service is stopped, so the message journal must hold that backlog until processing resumes. Start with the Upgrade Graylog guide and the release notes for each minor version you pass through.
- Backup order: Back up the MongoDB data and the Graylog configuration before changing any package version, so you can restore both if a step fails.
- Journal and input flow: Confirm the journal volume has room for the backlog that accumulates while the service is down, and check that input sources can resend if your journal is undersized.
- Dependency checks: Confirm MongoDB and the search backend meet the compatibility matrix for each target release before you start Graylog on that version.
- Configuration and automation: Review custom scripts and any API clients against the 6.1 and 6.3 notes, since API error types and permission changes can break them.
- One minor version at a time: Complete and verify each minor step before moving to the next, so a problem is tied to a single release.
After restart, confirm that the journal backlog drains, every input shows as running, and recent messages appear in search.
In a multi-node deployment, the Graylog servers, MongoDB replica set and search backend are spread across several hosts, and a load balancer distributes incoming traffic. The Graylog multi-node guide describes a layout with three Graylog and MongoDB nodes, three Data Nodes on their own cluster and a load balancer, with is_leader set to false on follower Graylog nodes. This layout lets you upgrade one node at a time while the rest of the cluster keeps running, but only if you control the order and keep versions consistent. Confirm the exact sequence for your target release in the upgrade notes before you begin.
- Node rotation: Remove one node from the load balancer, upgrade it, return it to rotation, and confirm health checks pass before moving to the next node.
- Leader handling: Confirm which node holds leadership and avoid changing the leader until the followers are on the target version.
- Version alignment: Keep every Graylog node on the same minor version before you advance to the next step, and upgrade the data tier and MongoDB in the order the release notes specify.
- Direct senders: Sources that send straight to one node's address lose messages while that node is down, because other nodes cannot read that node's journal, so route senders through the load balancer before the window.
- Journal per node: Each node buffers its own accepted messages, so check every node's journal drains, not only the cluster summary.
After the last node returns, check that all nodes report the same version, the leader role is where you expect, and the load balancer shows every backend healthy.
A Docker Compose stack packages Graylog, its MongoDB and its search backend as containers defined in one file, and the upgrade means changing image tags and restarting services. Compose makes the stack easy to reproduce, but it also makes it easy to replace a container without its data. The Graylog installation documentation covers Docker Compose as an install method, so the same compatibility rules apply to each image you change. Before you edit the file, record every image tag and every volume the stack uses.
- Image tags: Change the Graylog, Data Node and MongoDB image tags deliberately, and check each pair against the compatibility matrix rather than assuming the newest tag is supported.
- Container order: Bring up the backend services first, then Graylog, and stop Graylog before the backends so it does not write to a half-changed store.
- Volumes to protect: Back up the MongoDB data, the Graylog data directory and the journal volume, since a journal stored only in a container layer is lost when the container is recreated.
- Journal and input flow: Expect inputs to keep receiving messages during the restart, and confirm the journal volume is persistent before you stop the stack.
- Environment changes: Compare the new version's environment variables and ports with your existing file, because a renamed setting can stop the server from starting.
After the stack restarts, check that the journal drains, that each container reports healthy and that a known search returns current messages.
What makes a 6.x minor upgrade take longer
This table lists the factors that change how long a Graylog 6.1, 6.2 or 6.3 step takes and what to count before you plan. Read each row as a question to answer about your own environment, since the effect on effort grows with each item you cannot size. The main takeaway is that the API and plugin inventory usually decides the schedule more than the upgrade steps themselves.
| Effort driver | Effect on effort | What to inventory |
|---|---|---|
| Custom plugins | Each plugin must be checked against the release it targets and rebuilt or retested when its build or APIs change | Every in-house plugin, its build dependencies and the Graylog versions it was compiled against |
| API integrations using changed error types | Clients that parse APIError responses must handle RequestError for invalid requests from 6.1 onward | Scripts, SIEM connectors and automation that read Graylog API error responses or status fields |
| Report creator role dependencies | Enterprise reports from 6.3 need the report creator role, so users and dashboards may need role changes before reports keep working | Users who create or schedule reports, their current roles and any automation that creates reports |
| Input type permissions | Teams that restrict who manages inputs may need an input_types:create permission model planned and tested | Input creation workflows, role assignments and who currently owns input configuration |
| GreyNoise adapter removal | Content relying on the removed GreyNoise Community Data Adapter must be found and replaced or removed before the 6.1 step | Data adapters, lookup tables, pipelines and dashboards that reference GreyNoise |
| Cluster size and node count | More Graylog nodes and Data Nodes mean more rolling steps, version checks and journal monitoring between each restart | Node list, roles, load balancer targets and the sequence each node must follow |
| Data volume and backup duration | Larger indices and configuration stores lengthen the backup taken before each step and any restore if a rollback is needed | Index sizes, MongoDB data size, snapshot repository capacity and measured restore time in a test |
| Number of environments | Each environment, including development, test, staging and production, repeats the inventory, upgrade and validation work | Environment list, their differences in plugins, roles and data, and who signs off each one |
Questions teams ask before upgrading Graylog 6.x
What does a Graylog 6.x minor upgrade cost?
The cost is mostly the labor to plan, test and cut over, plus any change to your own automation. No supplied figure sets a price for this work, and DeployOpen does not publish one. Graylog Open is free to download and run, so software licensing is not the main line item for an open-source install. If you run Graylog Enterprise or Graylog Security, check that your license terms cover the version you move to. Ask a partner for a quote built from a written scope that lists the environments, the number of nodes, the scripts that call the API, and whether a rollback test is included. One-time work covers the upgrade itself. Recurring costs appear only if you buy a support retainer or keep a test environment running.
How long does a Graylog 6.1 to 6.3 upgrade take?
Duration depends on how many minor steps you take, how many nodes you run, and how much custom integration code you have. Graylog advises upgrading one minor version at a time, so a move from one 6.x release to 6.3 is a sequence of stops, each with its own checks. Check the duration with your vendor or internal team against your own environment, not a generic figure. The main drivers are the size of your MongoDB and Data Node clusters, the number of API clients that need changes, the time needed for the journal to drain after each restart, and the number of stakeholders who must sign off on dashboards and reports.
What does the internal team need to provide for the upgrade?
The team needs an inventory of what depends on Graylog, a test environment that mirrors production, and named owners for the affected areas. Engineers should be able to take a backup, restore it, and read the upgrade notes for each minor release. Someone must own API clients, since the 6.1 change to invalid-request errors can break code that matches error types. Security or compliance staff should confirm the roles for report creators and input types. Operations staff need a window for restarts and a way to watch the message journal during the cutover.
Can our internal team run the Graylog 6.x upgrade without a partner?
Yes, many teams do, provided they have engineers who have run Graylog in production and a non-production copy to test against. The upgrade notes are specific, so the work is mostly disciplined testing rather than new engineering. A partner adds value when your team lacks capacity, when the environment has several clusters or air-gapped networks, or when custom plugins and scripts need fixing. DeployOpen plans, implements, tests and documents self-hosted platforms inside your own infrastructure, and most engagements are fixed-scope with agreed deliverables in writing. Decide based on your staffing and risk tolerance.
Does Graylog Open or Enterprise licensing change the report and input type steps?
Yes, the licensing affects what you test. From Graylog 6.3, a user needs the report creator role to create Enterprise reports, so reporting access must be granted deliberately after the upgrade. Input type permissions use the input_types:create permission to limit users to specific input types, and this works in your role configuration regardless of edition. Graylog Open is licensed under SSPL-1.0, which is not an OSI-approved open source license, and some inputs and features need an Enterprise license. Confirm your edition against the pricing and product pages before you plan the change, and test role assignments for each team that owns reports or inputs.
What should we do if an API integration breaks after the 6.1 upgrade?
Start by checking the error type your client receives. In Graylog 6.1, invalid-request API errors are returned as RequestError instead of APIError, so any code that matches on the old type will misbehave even though the request itself is valid. Update the client to handle the new type, then rerun the integration tests against a staging server. Keep the old and new responses in your test fixtures so the change is visible in review. Record the fix in your change log, and check the release notes before you move to the next minor version, because each upgrade may add its own changes to the API.
How DeployOpen scopes and delivers a Graylog upgrade
DeployOpen plans and carries out Graylog 6.1, 6.2 and 6.3 upgrades inside your own infrastructure, one minor release at a time. Each step starts from a written scope that names the checks, changes and handover material before any work begins.
How we scope
- Inventory your current Graylog version, server nodes, MongoDB and search backend versions before agreeing a path.
- Map which 6.1, 6.2 and 6.3 breaking changes touch your API clients, plugins, entity permissions and report workflows.
- Agree the written scope, deliverables and timeline in advance; most engagements are fixed-scope, with ongoing support available as a retainer.
How we build
- Rehearse each minor step on a non-production copy of your configuration and data before touching production.
- Update API clients to expect RequestError responses in place of APIError, and test scripts that depend on the old error type.
- Review role assignments for the report creator role and input_types:create permission, then test access for each affected user group.
How we hand over
- Document the upgrade order, backups taken, version checkpoints and rollback points for each minor release in the path.
- Provide a record of changed permissions, removed adapters and API behavior changes so your team can audit the result.
- Walk your operators through post-upgrade checks, including input status, journal drain and dashboard and alert verification.
How we support
- Support the cluster after handover on a retainer covering questions about the new minor versions and follow-up fixes.
- Re-test custom integrations and in-house scripts whenever you plan the next Graylog upgrade step.
- Confirm with Graylog's upgrade notes and your own environment any change not covered in the agreed scope.
