Creating a systemd service to manage the agent
This guide is for users who download the Grafana Cloud Agent binary directly or build it from source and is completely optional. Most users get started by downloading the agent and running it directly, as instructed to do in the Grafana Cloud walkthrough inside the application.
Running the agent as a systemd service creates a long-living process that can automatically restart when killed or when the host is rebooted.
In this page we describe a way to create, manage, and enable a systemd service to automatically start at host boot time and restart. For more complex configuration possibilities, see the systemd documentation. This process requires admin rights to the host via sudo or root to create the
.service file and to manage systemd.
To begin, take note of the location on the host where you installed the agent binary and the agent-config.yaml file. Note: For simplicity, we recommend you put both in the same directory.
Step 1. Create a service file
We put our downloaded binary in
/usr/local/bin, so our service definition will use this binary path. For this example, we renamed the downloaded binary to
Create a file in
You may name it something else if you like, but you must end the file with
Insert the following into the file, and as you do, change the:
ExecStartvalue to match the location and name of the binary; if you put the
agent-config.yamlfile anywhere else, modify the location in the last part of that line
grafana-agentvalue to match the username on your host that will run the agent; we recommend creating a user specifically for the agent and running the agent as the new user, which we have intentionally named to match the service it will run
Note: To create a user, use
sudo useradd --no-create-home --shell /bin/false grafana-agent, where
--shell /bin/falseprevent the new user account from logging in directly to the server.
[Unit] Description=Grafana Cloud Agent [Service] User=grafana-agent ExecStart=/usr/local/bin/grafana-agent --config.file=agent-config.yaml Restart=always [Install] WantedBy=multi-user.target
Restart=always tells systemd to watch this service and restart it should it cease running.
WantedBy=multi-user.target tells systemd to load this service during boot at at time after the system is running, when all network services are started and the system is available for users to log in (but before the activation of a local GUI, which doesn’t matter on a server system that doesn’t run a GUI). If this is not included, the service will not start at system boot.
Save the file and move to Step 2.
Step 2. Manage your new service
Anytime you add or modify a
.service file in
/etc/systemd/system, you must reload the service files. To do so, enter:
sudo systemctl daemon-reload
To start the service:
sudo systemctl start grafana-agent.service
To check the status of the service:
sudo systemctl status grafana-agent.service
Checking the status will let you know whether everything is configured and running correctly, and if not, provide an error message to help you troubleshoot.
To stop the service:
sudo systemctl stop grafana-agent.service
To enable to service to run automatically on every reboot:
sudo systemctl enable grafana-agent.service
To stop the service from running automatically on every reboot:
sudo systemctl disable grafana-agent.service