https://github.com/pinpox/restard
Restart SystemD Services via Web-Hooks
https://github.com/pinpox/restard
devops nixos systemd webhook
Last synced: 8 months ago
JSON representation
Restart SystemD Services via Web-Hooks
- Host: GitHub
- URL: https://github.com/pinpox/restard
- Owner: pinpox
- Created: 2025-07-31T20:13:03.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-07-31T20:17:04.000Z (8 months ago)
- Last Synced: 2025-08-17T05:39:13.353Z (8 months ago)
- Topics: devops, nixos, systemd, webhook
- Language: Nix
- Homepage:
- Size: 7.81 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# RestarD
A simple Go service that listens for HTTP requests and restarts systemd
services. Designed for webhook-based deployments and service management, e.g. in
a CI. RestarD allows per-service authentication tokens and can be run secruely
with non-root users using dedicated polkit rules.
## Use Cases
- **Webhook Deployments**: Restart services after CI/CD deployments
- **Service Management**: Remote service restart for maintenance
- **Monitoring Integration**: Restart services from monitoring alerts
- **Container Orchestration**: Restart systemd services from containers
## Configuration
Configure each service via environment variables.
- `LISTEN_ADDR`: Server listening address (default: `:8080`)
- `RESTARD_SERVICE_`: Name of the systemd unit to restart on request to `/restart/`
- `RESTARD_TOKEN_`: Authentication token for the unit ``
### Example Configuration
The following configuration would listen on `127.0.0.1:8080` for incoming
requests. It would restart `nginx.service` if a request is made to
`/restart/web` with the token `hunter1` and restart `api.service` if a
request is made to `/restart/api` with the token `hunter2`.
```bash
export LISTEN_ADDR=127.0.0.1:8080
export RESTARD_SERVICE_WEB=nginx.service
export RESTARD_TOKEN_WEB=hunter1
export RESTARD_SERVICE_API=api.service
export RESTARD_TOKEN_API=hunter2
```
## Example Usage
The genheral API is:
```bash
POST /restart/{servicename}
Authorization: Bearer
```
And will respond with:
- **200**: Service restarted successfully
- **404**: Any error (service not found, invalid token, restart failed, etc.)
### Example
```bash
# Restart nginx.service
curl -X POST http://localhost:8080/restart/web \
-H "Authorization: Bearer your-secret-token"
# Restart myapi.service
curl -X POST http://localhost:8080/restart/api \
-H "Authorization: Bearer another-token"
```
## Running without root
Since RestarD will try to restart other units, it needs the appropiate
permissions. It can be run as root, then no additional configuration is
necessary. If you prefer running it as a lower-privileged user, add the
following polkit rule.
Create `/etc/polkit-1/rules.d/50-restard.rules`:
```javascript
polkit.addRule(function(action, subject) {
if (action.id == "org.freedesktop.systemd1.manage-units" &&
subject.user == "restard") {
// Allow only restart action
if (action.lookup("verb") == "restart") {
return polkit.Result.YES;
}
}
});
```
Exmaple Systemd unit, running as user `restard`
(`/etc/systemd/system/restard.service`):
```ini
[Unit]
Description=RestarD Service Restart API
After=network.target
[Service]
Type=simple
User=restard
Group=restard
ExecStart=/usr/local/bin/restard
Environment=LISTEN_ADDR=127.0.0.1:8080
Environment=RESTARD_SERVICE_WEB=nginx.service
Environment=RESTARD_TOKEN_WEB=your-secret-token
WorkingDirectory=/var/lib/restard
Restart=always
RestartSec=5
# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/restard
[Install]
WantedBy=multi-user.target
```
## NixOS Module
The flake includes a NixOS module for easy deployment:
```nix
{
inputs.restard.url = "github:pinpox/restard";
outputs = { nixpkgs, restard, ... }: {
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
modules = [
restard.nixosModules.default
{
services.restard = {
enable = true;
listen = "127.0.0.1:8080";
services = {
web = {
service = "nginx.service";
token = "/run/secrets/web-token";
};
api = {
service = "myapi.service";
token = "/run/secrets/api-token";
};
};
};
}
];
};
};
}
```
Additionally, there is a NixOS VM-test included for devlopment.
```
nix build .#checks.x86_64-linux.nixos-test -Lv
```
### Module Options
- `services.restard.enable` - Enable the restard service
- `services.restard.listen` - Listen address (default: `:8080`)
- `services.restard.services..service` - Systemd unit to restart
- `services.restard.services..token` - Path to token file
- `services.restard.user/group` - Service user/group (default: `restard`)
### Module Features
- **Dedicated user** - Runs as non-root `restard` user
- **Polkit integration** - Only allows restart operations
- **systemd credentials** - Tokens loaded securely via `LoadCredential`
- **Service hardening** - `NoNewPrivileges`, `ProtectSystem`, etc.
## Building & Testing
```bash
# Build the application
nix build
# Run tests (includes VM integration test)
nix flake check
```