How to Collect Linux System Logs with Elastic Agent and Fleet

Fleet-managed Elastic Agent lets you define a policy in Kibana, add integrations to that policy, and centrally distribute the resulting configuration to enrolled agents. For Linux system logs, the current System integration can collect auth and syslog data from traditional files or journald.

A common failure mode is stopping after the Agent shows Healthy in Fleet. Healthy means the agent is checking in; it does not prove that the specific log files or journald streams are readable and producing events. This tutorial verifies both control-plane health and actual log ingestion.

Last verified: September 10, 2026. The current System integration page reports version 2.23.4 and minimum Kibana 9.2.1. Do not use old Elastic 8.19 guide pages that explicitly state they are no longer updated.

What You'll Accomplish

You will:

1. create or select a Fleet agent policy;
2. add the current System integration;
3. enable the Linux auth and/or syslog streams you actually need;
4. enroll one Linux host with Fleet-managed Elastic Agent;
5. confirm the Agent becomes Healthy;
6. prove that fresh Linux log events arrive; and
7. fix common CA, network, version, journald, and file-permission problems.

Prerequisites

You need:

• Elasticsearch/Kibana or Elastic Cloud with Fleet available;
• a Kibana user with the current Fleet/Integrations privileges required by Elastic;
• a Linux host supported by the Agent/integration;
• outbound connectivity to Fleet Server and the configured output;
• root/sudo access for normal installation, or a planned unprivileged deployment;
• knowledge of whether your distribution uses files, journald, or both for system/auth logs.

Elastic allows only one normally installed Elastic Agent per host. Check for an existing Agent before installing another.

Quick Answer

In Kibana, add the System integration to an Elastic Agent policy and enable the Linux auth/syslog inputs appropriate to your distribution. Then go to Fleet → Agents → Add agent, choose that policy, keep Enroll in Fleet selected, and run the install/enrollment command generated for your host. After enrollment, confirm the Agent is Healthy. Then verify actual events in the System integration dashboards or Discover/data streams. If the Agent is Healthy but logs are missing, inspect the integration input settings and file/journald permissions; unprivileged Agent mode may need explicit read access to system log files.

Step 1: Choose or Create an Agent Policy

In Fleet, create a policy for the class of Linux hosts you are onboarding, or use an existing policy with the same collection requirements.

A policy is a set of inputs/settings distributed to agents enrolled in it. Each Agent can be enrolled in one policy.

Use names that reflect function and environment, for example:

linux-web-prod

instead of:

Policy 7.

Avoid adding unrelated integrations to a single universal policy if different server groups need materially different permissions and data.

Step 2: Add the System Integration

In Kibana:

1. open Integrations;
2. find System;
3. choose Add System;
4. configure the desired streams;
5. attach it to the intended Agent policy;
6. save and continue.

Elastic's current integration-policy documentation also allows adding integrations from Fleet's Agent policy view.

The System integration contains both metrics and logs. If this tutorial's objective is Linux logs, enable only the streams you need rather than assuming every dataset should be collected.

Step 3: Choose File or Journald Inputs

The current System integration supports Linux auth and syslog from:

• traditional log files; or
• journald.

Both can be enabled, and conditions can select where each runs.

Choose according to your distribution and logging architecture.

Common traditional paths vary by distribution. Do not hard-code /var/log/auth.log or /var/log/secure across every Linux host without checking the System integration's current defaults/configuration.

For journald, verify the Agent identity has permission to read the journal.

Step 4: Enroll the Linux Agent

Go to Fleet → Agents → Add agent.

Select:

• the intended policy;
• Enroll in Fleet;
• your operating system/architecture.

Fleet generates installation and enrollment commands containing deployment-specific URL/token values.

Use the generated command. Do not publish or reuse someone else's enrollment token.

Elastic's current docs state that Fleet-managed Agent connects to a trusted Fleet Server to obtain policy updates and reports Agent events.

Certificate caution

If enrollment reports:

x509: certificate signed by unknown authority

Elastic documents --insecure as a possible non-production workaround for self-signed certificates.

Do not normalize --insecure for production. Fix the CA/trust configuration and use a trusted certificate path.

Step 5: Verify Fleet Control-Plane Health

After installation, open the Fleet Agents page.

Confirm:

• the expected host is present;
• it is assigned to the expected policy;
• its state becomes Healthy;
• last check-in is current.

If it remains Enrolling, Elastic recommends confirming that the elastic-agent process is running.

On a standard Linux tar installation, Elastic documents Agent files under /opt/Elastic/Agent/, with logs below its data/elastic-agent-*/logs/ hierarchy. DEB/RPM layouts differ.

Step 6: Verify Actual System Log Ingestion

Do not stop at Healthy.

Generate a harmless system event appropriate to your environment, such as a normal sudo command in a test shell or another non-sensitive syslog event.

Then verify fresh events from the expected dataset in Kibana.

Look for evidence such as:

• data_stream.dataset corresponding to system auth/syslog;
• current @timestamp;
• the expected host.name;
• a recognizable but non-sensitive message/process.

The System integration currently documents separate auth and syslog data streams for Linux.

If events do not arrive, the control plane may be healthy while the data input is unreadable.

Step 7: Diagnose Permissions

Permission problems are especially important in unprivileged mode.

Elastic's current unprivileged-mode documentation explicitly shows System integration failures when Elastic Agent cannot open system log files and recommends granting read permission to the elastic-agent group for the required file.

Do not solve every permissions error by switching the Agent to root.

Instead:

1. identify the exact file/journal access that fails;
2. grant the smallest documented group/file permission needed;
3. restart/recheck if required; and
4. confirm that events arrive.

If an integration requires administrative access, current Elastic Agent restrictions can prevent switching to unprivileged mode while that policy is active.

Step 8: Verify Policy Version Compatibility

Current Fleet integration management warns when an integration has a minimum Elastic Agent version above agents in the target policy.

The policy can still be saved, but incompatible agents will not receive unsupported input configuration until they are upgraded.

If a System integration change appears in Kibana but a host never begins collecting the new dataset:

• inspect the Agent version;
• inspect the integration minimum;
• review Fleet's compatibility warning; and
• upgrade the Agent through your normal change process if required.

Verify the Setup

Collection is complete only when:

• the Agent is enrolled in the intended policy;
• Fleet shows a current Healthy check-in;
• the System integration is attached to that policy;
• intended auth/syslog inputs are enabled;
• a fresh, known Linux system event is visible in Elastic;
• host/dataset fields identify the correct source;
• Agent logs show no persistent permission/input errors.

A Healthy Agent without events fails this verification.

Common Problems and Fixes

Problem: Agent stays Enrolling

Cause: Agent process not running, Fleet Server unreachable, token/URL incorrect, or TLS trust failure.

Fix: check the local process/logs, Fleet Server URL, DNS/network egress, and certificate chain.

Problem: x509 unknown authority

Cause: Fleet Server uses a certificate the host does not trust.

Fix: install/configure the correct CA. Use --insecure only as the temporary non-production diagnostic path Elastic documents.

Problem: Agent is Healthy but no syslog events arrive

Cause: wrong stream/input, wrong file path, journald conditions, or insufficient read permissions.

Fix: inspect System integration settings and Agent logs. Confirm a fresh source event exists and that the Agent identity can read it.

Problem: Unprivileged mode misses system logs

Cause: the elastic-agent group/user lacks access.

Fix: grant only the required read permission according to current Elastic guidance. Recheck dashboards/events after the permission change.

Problem: Integration updates do not affect an older Agent

Cause: the package now requires a newer Elastic Agent.

Fix: review Fleet's version warning and upgrade the Agent before assuming policy distribution is broken.

Problem: Agent is Healthy but data goes to the wrong environment

Cause: wrong Agent policy/output/namespace.

Fix: inspect the policy assignment and output. Verify data_stream.namespace and host identity in ingested events.

Best Practices

Validate one host before fleet rollout

Use a representative Linux host to verify permissions, journal/file paths, policy assignment, and event shape.

Treat enrollment tokens as secrets

Do not publish generated enrollment commands with live tokens.

Prefer a trusted CA

Do not leave --insecure in production automation.

Separate control-plane and data-plane health

Agent Healthy answers one question. Fresh events answer another. Monitor both.

Use least privilege deliberately

Unprivileged mode can work, but integrations may need explicit file/group access. Document those grants.

Keep policy scope understandable

A policy should correspond to a meaningful class of hosts, not become a dumping ground for every integration.

When This Setup Makes Sense

Fleet-managed Elastic Agent is useful when you want central management of many agents and integrations from Kibana.

A standalone Agent may fit environments where Fleet is unavailable or configuration is managed fully as code. If your organization already uses another log shipper, migrating should be an architecture decision rather than adding duplicate collection.

FAQ

Why is Elastic Agent Healthy but no Linux logs appear?

Healthy means the Agent is checking in. The System integration may still have wrong inputs or insufficient permissions. Verify a fresh source event and inspect Agent logs.

Can Elastic Agent run without root?

Elastic supports unprivileged mode, but some integrations/data streams require permissions that must be granted explicitly, and some policies can require administrative access.

Which System integration version was current during verification?

The Elastic docs page showed System integration 2.23.4 with minimum Kibana 9.2.1 on September 10, 2026.

Should I use old Elastic 8.19 Fleet guides?

No for current procedures. Those pages explicitly state they are no longer updated. Use the current /docs/reference/ documentation.

Conclusion

Successful Fleet onboarding has two proof points: the Agent is healthy and the expected data arrives. Add the System integration to a clear policy, enroll one host with the generated command, verify Fleet health, then generate and find a fresh Linux event.

When ingestion fails, diagnose the exact layer—Fleet connectivity, version compatibility, input selection, journald/file source, or permissions—instead of repeatedly reinstalling the Agent.

References

1. Elastic Docs — "System Integration" — https://www.elastic.co/docs/reference/integrations/system — accessed September 10, 2026.
2. Elastic Docs — "Install Fleet-managed Elastic Agents" — https://www.elastic.co/docs/reference/fleet/install-fleet-managed-elastic-agent — accessed September 10, 2026.
3. Elastic Docs — "Add an integration to an Elastic Agent policy" — https://www.elastic.co/docs/reference/fleet/add-integration-to-policy — accessed September 10, 2026.
4. Elastic Docs — "Run Elastic Agent without administrative privileges" — https://www.elastic.co/docs/reference/fleet/elastic-agent-unprivileged — accessed September 10, 2026.
5. Elastic Docs — "Installation layout" — https://www.elastic.co/docs/reference/fleet/installation-layout — accessed September 10, 2026.