> ## Documentation Index
> Fetch the complete documentation index at: https://tally.wharflab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# tally/prefer-canonical-stopsignal

> STOPSIGNAL should use canonical signal names for clarity and consistency.

STOPSIGNAL should use canonical signal names for clarity and consistency.

| Property | Value      |
| -------- | ---------- |
| Severity | Info       |
| Category | Style      |
| Default  | Enabled    |
| Auto-fix | Yes (safe) |

## Description

`STOPSIGNAL` accepts signal names in many formats: numeric values (`9`, `15`),
names without the `SIG` prefix (`TERM`, `QUIT`), quoted strings (`"SIGINT"`),
mixed case (`sigterm`), and non-standard real-time signal names (`RTMIN+3`).

While Docker accepts all of these, canonical signal names are easier to read and
easier to connect to upstream daemon documentation. This rule suggests the
canonical form:

* Ordinary signals: `SIGTERM`, `SIGINT`, `SIGQUIT`, `SIGKILL`, etc.
* Real-time signals: `SIGRTMIN+3`

Environment variable references (e.g. `STOPSIGNAL $MY_SIGNAL`) are skipped because
the signal value cannot be determined statically.

Windows stages are skipped because `STOPSIGNAL` has no effect on Windows
containers — POSIX signals are not delivered to Windows processes.

## References

* [Dockerfile reference -- STOPSIGNAL](https://docs.docker.com/reference/dockerfile/#stopsignal)
* [signal(7) -- Linux manual page](https://man7.org/linux/man-pages/man7/signal.7.html)

## Examples

### Bad

```dockerfile theme={null}
FROM alpine:3.20
# Numeric signal value
STOPSIGNAL 15
CMD ["/app"]
```

```dockerfile theme={null}
FROM nginx:1.27
# Missing SIG prefix
STOPSIGNAL QUIT
CMD ["nginx", "-g", "daemon off;"]
```

```dockerfile theme={null}
FROM postgres:16
# Quoted signal name
STOPSIGNAL "SIGINT"
CMD ["postgres"]
```

```dockerfile theme={null}
FROM fedora:40
# Non-canonical real-time signal
STOPSIGNAL RTMIN+3
CMD ["/sbin/init"]
```

### Good

```dockerfile theme={null}
FROM alpine:3.20
STOPSIGNAL SIGTERM
CMD ["/app"]
```

```dockerfile theme={null}
FROM nginx:1.27
STOPSIGNAL SIGQUIT
CMD ["nginx", "-g", "daemon off;"]
```

```dockerfile theme={null}
FROM postgres:16
STOPSIGNAL SIGINT
CMD ["postgres"]
```

```dockerfile theme={null}
FROM fedora:40
STOPSIGNAL SIGRTMIN+3
CMD ["/sbin/init"]
```

## Auto-fix

The fix replaces the non-canonical signal token with its canonical form:

```bash theme={null}
tally lint --fix Dockerfile
```

The fix uses `FixSafe` safety because the canonical form is semantically identical
to the original — Docker normalizes signal names internally, so no runtime behavior
changes.

## Configuration

```toml theme={null}
[rules.tally.prefer-canonical-stopsignal]
severity = "info"  # Options: "off", "error", "warning", "info", "style"
```