grafito

Grafito is a simple, self-contained web-based log viewer for journalctl. It provides an intuitive interface to browse and filter system logs directly from your web browser.

Key features include:

• Real-time log viewing (with an optional auto-refresh).
• Filtering by unit, tag, time range, and a general search query.
• A dynamic user interface powered by HTMX for a smooth experience.
• Embedded assets (HTML, favicon) for easy deployment as a single binary.
• Built with the Crystal programming language and the Kemal web framework.

Installation

If you are using Arch Linux grafito is available in AUR

Using the Install Script (Linux with systemd)

For a quick installation on Linux systems with systemd, you can use the provided installation script. This script will:

1. Download the correct Grafito binary for your system's architecture (amd64 or arm64) for the latest version tagged in the script.
2. Install it to /usr/local/bin/grafito.
3. Set up and enable a systemd service for Grafito.

To use the script, run the following command:

curl -sSL https://grafito.ralsina.me/install.sh | sudo bash

After installation, Grafito should be running and accessible at http://<your_server_ip>:1111 (or the port configured in the service). You can check its status with systemctl status grafito.service.

Prebuilt Binaries

To install from prebuilt binaries, download the latest release from the releases page. The binaries are available for linux, both x86_64 and arm64 architectures. You can get an example grafito.service from the repository.

Install from source:

1. Clone the repository:

   git clone https://github.com/ralsina/grafito.git
   cd grafito
   

2. Install Crystal dependencies:

   shards install
   

3. Build the application:

   shards build --release
   

   This will create a single executable file named bin/grafito

Run using Docker

It doesn't make much sense to run Grafito in a container, but if you want to:

docker run -p 3000:3000 -v/var/log/journal:/var/log/journal ghcr.io/ralsina/grafito:latest

Or if you are using ARM:

docker run -p 3000:3000 -v/var/log/journal:/var/log/journal ghcr.io/ralsina/grafito-arm64:latest

Usage

Simply run the compiled binary:

./bin/grafito

Then open your web browser and navigate to http://localhost:3000 (or the port specified if configured differently).

The application requires journalctl and systemctl to be available on the system where it's run.

Running with systemd

To run Grafito as a systemd service, you can create a service file.

1. Create the service file:

   Create a file named grafito.service in /etc/systemd/system/ (or ~/.config/systemd/user/ for a user service) with the following content. Adjust paths and user/group as necessary.

   [Unit]
   Description=Grafito Log Viewer
   After=network.target
   
   [Service]
   Type=simple
   DynamicUser=yes
   # If set to "systemd-journal" it can access all logs in the system
   # Change if that is not what you want.
   Group=systemd-journal
   
   # --- Authentication Configuration ---
   # Set these environment variables to enable Basic Authentication.
   # If GRAFITO_AUTH_USER and GRAFITO_AUTH_PASS are not set, Grafito will run without authentication.
   Environment="GRAFITO_AUTH_USER=your_grafito_username"
   Environment="GRAFITO_AUTH_PASS=your_strong_grafito_password"
   
   # Replace with the actual path to your Grafito directory
   WorkingDirectory=/usr/local/bin/
   # Replace with the actual path and options to the Grafito binary
   ExecStart=/usr/local/bin/grafito -b 0.0.0.0 -p 1111
   Restart=on-failure
   
   [Install]
   WantedBy=multi-user.target
   

2. Reload systemd daemon:

   sudo systemctl daemon-reload
   

3. Enable the service (to start on boot):

   sudo systemctl enable grafito.service
   

4. Start the service:

   sudo systemctl start grafito.service
   

5. Check the status:

   sudo systemctl status grafito.service
   

Journald Permissions

By default, journalctl (and therefore Grafito) can only access the logs of the user running the command. To allow Grafito to access all system logs, the user running the Grafito process needs to be part of a group that has permissions to read system-wide journal logs.

Typically, this is the systemd-journal group (the name might vary slightly depending on your Linux distribution).

1. Add the user to the systemd-journal group: Replace your_user with the actual username that will run the Grafito process.

   sudo usermod -a -G systemd-journal your_user
   

2. Apply group changes: The user will need to log out and log back in for the new group membership to take effect. If Grafito is already running as a service under this user, you might need to restart the service:

   sudo systemctl restart grafito.service
   

Alternatively, if you are running Grafito directly (not as a service) and want to grant it temporary access for a session, you might run it with sudo, but this is generally not recommended for web applications for security reasons. Configuring the user with appropriate group membership is the preferred method.

Security Note: Granting access to all system logs means that any user who can access Grafito will be able to see these logs. Ensure that Grafito itself is appropriately secured if it's exposed to untrusted networks.

Logs from multiple hosts

Systemd Journald offers mechanisms to centralize logs from multiple hosts onto a single machine. This is particularly useful for managing logs in a distributed environment. Two common tools for this are systemd-journal-remote and systemd-journal-upload.

• systemd-journal-upload: This service runs on client machines and uploads their local journal entries to a remote systemd-journal-remote instance. It can be configured to send logs securely over HTTPS.
• systemd-journal-remote: This service runs on a central log server and listens for incoming journal data (typically via HTTP/HTTPS) from systemd-journal-upload instances. It then stores these logs in the local journal on the central server.

When logs from multiple hosts are consolidated onto the server where Grafito is running, each log entry will typically retain its original _HOSTNAME field. This is where Grafito's Hostname filter becomes very useful.

By using the "Hostname" filter in the Grafito UI, you can easily isolate and view logs originating from a specific client machine, even though all logs are stored and queried on the central Grafito server. For example, if you have logs from server1, server2, and web-node-alpha all being sent to your Grafito host, you can simply type server1 into the Hostname filter to see only its logs.

Configuration Sketch

1. On the Central Log Server (where Grafito runs):

   • Install and configure systemd-journal-remote to listen for incoming logs. You'll typically configure it to use HTTPS for security.
   • Ensure the journal on this server has enough storage space.

2. On Each Client Host:

   • Install and configure systemd-journal-upload.
   • Point it to the address and port of your central systemd-journal-remote instance.
   • Configure necessary authentication (e.g., client certificates) if HTTPS is used.

Once set up, logs from all client hosts will appear in Grafito on the central server, and you can use the Hostname filter to distinguish between them. Refer to the official systemd documentation for detailed instructions on configuring systemd-journal-remote and systemd-journal-upload.

Development

1. Prerequisites:

   • Ensure you have Crystal installed.
   • Ensure journalctl and systemctl are available on your development machine.

2. Clone and Setup: Follow the "Install from source" instructions above to clone the repository and install dependencies using shards install.

3. Run for Development: To run the application locally with automatic recompilation on changes, you can use a tool like Sentry.cr or simply recompile and run manually:

   shards run grafito
   

   The application will typically be available at http://localhost:3000.

4. Linting: This project uses Ameba for static code analysis. To run the linter:

   ./bin/ameba
   

Contributing

1. Fork it (https://github.com/ralsina/grafito/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Roberto Alsina - creator and maintainer