tailscalesd/README.md

# tailscalesd

> Service discovery for tailscale

Repository: https://guardianproject.dev/ops/tailscalesd

Returns a list of services for Prometheus to scrape, with some extra smarts for Guardian Project Ops.

See [the prometheus docs][0] for more information on the HTTP service discovery format.

[0]: https://prometheus.io/docs/prometheus/latest/http_sd/

## Example

`curl -H "Authorization: Bearer supersecret" http://tailscalesd:9242`

``` json
[
  {
    "labels": {
      "__meta_tailscale_device_client_version": "1.52.1-t75d3c9385-g3e9627f3b",
      "__meta_tailscale_device_hostname": "gp-ourapp-prod-main",
      "__meta_tailscale_device_authorized": "true",
      "__meta_tailscale_device_id": "1234678910",
      "__meta_tailscale_device_name": "gp-ourapp-prod-main.rocky-rocks.ts.net",
      "__meta_tailscale_device_os": "linux",
      "__meta_tailscale_tailnet": "ourtailnet"
    },
    "targets": [
      "100.100.100.101"
    ]
  },
  {
    "labels": {
      "__meta_tailscale_device_client_version": "1.52.1-t75d3c9385-g3e9627f3b",
      "__meta_tailscale_device_hostname": "ip-10-10-10-10",
      "__meta_tailscale_device_authorized": "true",
      "__meta_tailscale_device_id": "123456789101",
      "__meta_tailscale_device_name": "ip-10-31-0-182.rocky-rocks.ts.net",
      "__meta_tailscale_device_os": "linux",
      "__meta_tailscale_tailnet": "ourtailnet"
    },
    "targets": [
      "100.100.100.102"
    ]
  }
]
```

## Usage

### Deploy on NixOS

Use the exported NixOS module from this repository:

- `nixosModules.tailscalesd`

Provide secrets via systemd credentials (`LoadCredential`) through:

- `services.tailscalesd.credentials.bearerTokenFile`
- `services.tailscalesd.credentials.clientIdFile`
- `services.tailscalesd.credentials.clientSecretFile`

### Configuration

Configuration values can be set using environment variables, or optionally loaded from an environment file. The settings include:

- **host** (`TAILSCALESD_HOST`): The host address on which the application will bind (designed to be used in a container, BE CAREFUL!). Default is `0.0.0.0`.
- **port** (`TAILSCALESD_PORT`): The port number on which the application will be accessible. Default is `9242`.
- **interval** (`TAILSCALESD_INTERVAL`): The interval on which the Tailscale API is polled in seconds. Default is `60`.
- **bearer_token** (`TAILSCALESD_BEARER_TOKEN`): The authentication token passed in the Authorization header (required).
- **tailnet** (`TAILSCALESD_TAILNET`): The Tailscale tailnet identifier (required).
- **client_id** (`TAILSCALESD_CLIENT_ID`): The Tailscale oauth client id (required).
- **client_secret** (`TAILSCALESD_CLIENT_SECRET`): The Tailscale oauth client secret (required).
- File-based secret alternatives:
  - `TAILSCALESD_BEARER_TOKEN_FILE`
  - `TAILSCALESD_CLIENT_ID_FILE`
  - `TAILSCALESD_CLIENT_SECRET_FILE`

For systemd services, prefer `LoadCredential=` plus `%d` (runtime `CREDENTIALS_DIRECTORY`) and set `TAILSCALESD_*_FILE` values to files under `%d`.

#### Environment File

You can also specify an environment file to load configuration values. The path to the environment file should be set in the `TAILSCALESD_ENV_FILE` environment variable. All of the config values can be provided in the env file.

**Example Environment File** (`env`):

```env
TAILSCALESD_TAILNET=my-tailnet
TAILSCALESD_CLIENT_ID=xxxx
TAILSCALESD_CLIENT_SECRET=yyyyy
TAILSCALESD_HOST=127.0.0.1
TAILSCALESD_BEARER_TOKEN=supersecret
```

### Monitoring


This service provides the following Prometheus metrics:

- `tailscalesd_unhandled_background_task_crashes`
  - **Type**: Counter
  - **Description**: The number of unhandled background task crashes. This counter increases every time a background task crashes without being handled by the application.
- `tailscalesd_matrix_sd_down`
  - **Type**: Counter
  - **Description**: The number times a matrix sd host was unreachable. This counter increments each time a connection attempt to a matrix sd host fails.
  - **Labels**:
    - `device_hostname`: The hostname of the device that was unreachable.
- `tailscalesd_polling_up`
  - **Type**: Gauge
  - **Description**: Indicates if tailscalesd can access the tailscale devices API up (1) or down (0)

It also provides HTTP server metrics from [trallnag/prometheus-fastapi-instrumentator](https://github.com/trallnag/prometheus-fastapi-instrumentator)

## Dev

### Running the Application

1. **Install Dependencies**: Ensure that all required dependencies are installed.

    ```sh
    uv sync --all-groups
    ```

2. **Set Configuration**: Set the necessary environment variables or create an environment file with the configuration values.

3. **Start the Application**: Run the application using the following command:

    ```sh
    uv run tailscalesd
    ```

4. **Access the Application**: The application will be accessible at `http://<host>:<port>`.