Skip to content

Commit

Permalink
docs: update readme with tons of small things
Browse files Browse the repository at this point in the history
  • Loading branch information
PlexSheep committed Jan 7, 2025
1 parent 337d954 commit 759e7a1
Showing 1 changed file with 97 additions and 13 deletions.
110 changes: 97 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
![GitHub language count](https://img.shields.io/github/languages/count/PlexSheep/netpulse)
[![Rust CI](https://github.com/PlexSheep/netpulse/actions/workflows/cargo.yaml/badge.svg)](https://github.com/PlexSheep/hedu/actions/workflows/cargo.yaml)

Keep track of your internet connection with a daemon
Keep track of your internet connection with a daemon. Licensed under MIT.

- [GitHub](https://github.com/PlexSheep/netpulse)
- [crates.io](https://crates.io/crates/netpulse)
Expand All @@ -17,6 +17,56 @@ Keep track of your internet connection with a daemon
My ISP has trouble pretty much every year some month delivering constant uptime,
Netpulse helps keep track of when your internet connectivity goes down.

## Platform Support

- Primary support: GNU/Linux x86_64
- Other architectures: May work but untested
- Windows: Not supported
- macOS: Unknown/untested

I have it running on my homeserver and laptop with Debian based modern Operating
Systems.

## How it Works

Netpulse performs comprehensive connectivity checks using multiple methods:

1. HTTP Checks: Makes HTTP requests to test application-layer connectivity
2. ICMP Checks: Sends ping requests to test basic network reachability
3. Dual-Stack: Each check is performed over both IPv4 and IPv6 to monitor both network stacks

The daemon performs these checks every 60 seconds against reliable targets
(currently Cloudflare's DNS servers). This multi-protocol approach helps
distinguish between different types of connectivity issues.

## Installation

### Via Cargo

The simplest way to install Netpulse is through Cargo:

```bash
cargo install netpulse
```

This will install both the `netpulse` and `netpulsed` executables.

### System Setup

After installing the binaries, you'll need to set up the daemon environment:

```bash
sudo netpulsed --setup
```

This will:

- Create the netpulse user and group
- Copy the `netpulsed` executable to `/usr/local/bin/`
- Create necessary directories and set permissions
- Install a systemd unit file
- Configure logging

## Usage

Netpulse has two parts:
Expand All @@ -34,32 +84,66 @@ seconds.

### The Daemon

The daemon of Netpulse can be started, ended and so on with the `netpulsed`
executable.
The `netpulsed` daemon can be run either through systemd (recommended) or as a standalone process.

A simple `sudo netpulsed --start` will let the daemon run until you stop it or
your system shuts down. Root privileges are required for starting and setup,
but privileges will be dropped to the user `netpulse` with the group
`netpulse`.
#### Using Systemd (Recommended)

To set everything up, including a systemd unit file, a user, and copying the `netpulsed`
executable to `/usr/local/bin/`, do the following:
After running the setup (`sudo netpulsed --setup`), you can manage the daemon using standard systemd commands:

```bash
netpulsed --setup
sudo systemctl start netpulsed.service # Start the daemon
sudo systemctl stop netpulsed.service # Stop the daemon
sudo systemctl status netpulsed.service # Check daemon status
```

#### Updating
#### Running Standalone

Just run `netpulsed --setup` again, and restart the systemd service with
`systemctl restart netpulsed.service` if you use that.
You can also run `netpulsed` directly as a regular program. Note that root privileges are required for setup, but the daemon will drop privileges to the `netpulse` user and group during operation.

#### Logging

The daemon's log level can be controlled using the `NETPULSE_LOG_LEVEL` environment variable. Valid values are:

- `error`
- `warn`
- `info` (default)
- `debug`
- `trace`

For example:

```bash
NETPULSE_LOG_LEVEL=debug netpulsed --start
```

### The Reader

You can use `netpulse --test` to run the checks the daemon would run and see the
status. Just using `netpulse` without arguments will result in it trying to load
and analyze the store.

### Updating

There are two steps to updating Netpulse:

1. Update the binaries:

```bash
cargo install netpulse
```

2. Update the system configuration:

```bash
sudo netpulsed --setup
```

3. If using systemd, restart the service:

```bash
sudo systemctl restart netpulsed.service
```

### Files and Directories

`netpulsed` will try to create a few directories / files:
Expand Down

0 comments on commit 759e7a1

Please sign in to comment.