# gl_spy User & Bandwidth Monitor

`gl_spy` is a real-time, interactive ncurses-based monitoring tool for glFTPd. It reads the server's shared memory segment (`struct ONLINE`) to display online users, their primary group, active transfers (upload/download speed and current file), idle times, and site-wide bandwidth totals.

---

## Command Line Usage

```bash
gl_spy [-r <path>] [-t <rate>] [-s <mode>] [-e]
```

### Options

| Flag | Argument | Description | Default |
|------|----------|-------------|---------|
| `-r` | `<path>` | Path to alternative configuration file | `/etc/glftpd.conf` |
| `-t` | `1..32`  | Screen refresh rate (1 = slowest, 32 = fastest) | `15` |
| `-s` | `<mode>` | Initial user sort criteria | `u` (Username) |
| `-e` | None     | Show all slots including inactive/empty slots | Inactive slots hidden |
| `-h` | None     | Display command line help and keybindings | |

#### Sort Modes (`-s <mode>`)
- `u` or `U`: **Username** (alphabetical, case-insensitive A–Z)
- `g` or `G`: **Group** (alphabetical, case-insensitive A–Z)
- `p` or `P`: **Process ID** (PID, numerical)
- `a` or `A`: **Activity** (Uploaders $\to$ Downloaders $\to$ Active Commands $\to$ Idle)
- `b`, `s`, `B`, `S`: **Transfer Speed** (highest transfer rate first)
- `i` or `I`: **Idle Time** (most recently active first)
- `0` or `n`: **Slot Order** (raw shared-memory slot order)

---

## Interactive Keybindings

### Navigation
- **`Up` / `Down`**: Move cursor up or down by one user
- **`Page Up` / `Page Down`**: Scroll through user list by full page
- **`Home` / `End`**: Jump directly to the top or bottom of the list

### Sorting & Display Filters
- **`s`**: Cycle sort mode forward (`Username` $\to$ `Group` $\to$ `PID` $\to$ `Activity` $\to$ `Speed` $\to$ `Idle` $\to$ `Slot`)
- **`S`**: Cycle sort mode backward
- **`o` / `O`**: Toggle reverse sort order (Ascending / Descending)
- **`u`**: Sort immediately by Username
- **`g`**: Sort immediately by Group
- **`p`**: Sort immediately by PID
- **`a`**: Sort immediately by Activity
- **`b`**: Sort immediately by Transfer Speed
- **`i`**: Sort immediately by Idle Time
- **`0`**: Sort immediately by Slot Order
- **`e`**: Toggle hiding/showing empty slots (compact mode vs all slots)

### User Actions & Details
- **`Enter`**: Toggle detailed user modal (shows username, group, tagline, PID, current working directory, remote host/IP, login time, SSL mode, and total time online)
- **`k`**: Kick highlighted user session with `SIGTERM` (requires root privileges)

### View & Refresh Controls
- **`+` / `-`**: Increase / decrease refresh rate by 1
- **`>` / `<`**: Increase / decrease refresh rate by 5
- **`r`**: Force screen redraw and re-read terminal dimensions
- **`h` / `?`**: Toggle help screen popup
- **`q` / `ESC`**: Quit `gl_spy` (or close active popup window)

---

## Technical Notes

- `gl_spy` attaches to the shared memory segment configured by `ipc_key` in `glftpd.conf` (default key `0x0000DEAD`).
- By default, inactive slots are filtered out so that servers with large `max_users` allocations (e.g. 50–200 slots) only display active users in a compact, readable list without blank gaps.
- Cursor selection automatically tracks the selected user session across screen refreshes, preventing unwanted jumps when other users log in or disconnect.
